Skip to main content

Authentication Guide

Aethrix Studio configures authentication per operation from the Authentication tab of the request editor. The tab header shows an info badge whenever authentication is active.

Authentication is built around two complementary concepts:

  • Authentication Profiles (named, reusable credentials stored in an Environment) — the primary control.
  • Inline (Manual) configuration — entered directly on the request, useful for one-off or quick tests.

A separate client certificate (mTLS) option is available for every protocol and is configured independently of the profile/mode above.

Authentication Profiles — the Credential dropdown​

The top of the Authentication tab is the Credential: dropdown. It lists every compatible, named authentication profile defined in the active Environment, plus two synthetic entries:

EntryMeaning
A named profile (e.g. My API, Prod OAuth)Reuse a stored credential. Selecting it applies that credential to the request.
Manual (inline)Configure authentication directly on this request (see Inline authentication).
AnonymousNo authentication is sent (public or pre-authenticated endpoints).

What you see after selecting an entry:

  • Named profile selected — a read-only summary appears: "Using selected authentication profile. Switch to "Manual (inline)" to override per-request." A masked hint is shown underneath, e.g. Username: joh***, Token: eyJh***, or OAuth2 — token valid until 14:05:33. No inline fields are editable; update the profile once to affect every request that uses it.
  • Manual (inline) selected — the inline authentication fields are shown (see below).
  • Anonymous selected — nothing is sent.

The dropdown is protocol-aware: only profiles whose type matches the current service are listed. HTTP/gRPC services see Username & Password-type, Token-type, and OAuth2-type profiles; Kafka services see the Kafka-specific profile types.

tip

Profiles are the recommended approach for anything you will reuse. Keep secrets in one place, and rotate them in a single profile instead of editing many requests.

Creating and managing profiles​

  1. In the Authentication tab, click the search icon next to the Credential: dropdown (tooltip: "Manage authentication credentials").

  2. The Environment Management window opens on the Credentials tab.

  3. Click Add Profile (tooltip: "Add a new authentication profile"). A dialog prompts "Name the new authentication profile" with a Name: field — enter a profile name and confirm.

  4. In the right-hand panel, set the Type: by choosing one of the available profile kinds (the Profile Name: field already holds the name you entered):

    Profile typeUsed for
    HTTP BasicHTTP Basic auth (Authorization: Basic)
    HTTP Digest⚠️ Not implemented — see the note below the table
    HTTP Windows (NTLM)⚠️ Not implemented — see the note below the table
    Bearer TokenStatic bearer token (Authorization: Bearer)
    API Key (Header)API key sent as a request header
    API Key (Query)API key sent as a query parameter
    OAuth2 FlowFull OAuth 2.0 / OpenID Connect flow (see below)
    Kafka SASL PlainKafka SASL/PLAIN
    Kafka SASL Scram 256Kafka SASL/SCRAM-SHA-256
    Kafka SASL Scram 512Kafka SASL/SCRAM-SHA-512
    Kafka SASL GSSAPIKafka SASL/GSSAPI (Kerberos)
    Kafka OAuthBearerKafka SASL/OAUTHBEARER
warning

HTTP Digest and HTTP Windows (NTLM) do not work yet. A profile of either kind sends a pre-emptive Authorization: Basic header built from the same username and password — the server that expects a Digest challenge (401 with WWW-Authenticate: Digest) or Windows integrated authentication will keep rejecting the request, with nothing in the response to say why. Choosing Digest or Windows (NTLM) as an inline mode sends no Authorization header at all. These two entries remain in the UI while they are being implemented, so until then use HTTP Basic where the server accepts it, or carry the credential yourself in a header. mTLS (Client Certificate) and the OAuth 2.0 flows are unaffected.

  1. Fill in the credential fields for the chosen type, then close the window. Click Delete Profile to remove the selected profile.
note

You can also pre-select a default profile per service: when you open an operation, Aethrix automatically selects the default profile configured for that service in the Environment.

Inline authentication (Manual)​

Select Manual (inline) in the Credential: dropdown to configure authentication directly on the request. An Authentication Mode: combobox appears (it also has a Reset to default values button to restore the OAuth 2.0 default profile). The available modes are:

  • Basic
  • Bearer Token
  • Digest — ⚠️ not implemented; sends no Authorization header (see the warning above)
  • Windows (NTLM) — ⚠️ not implemented; sends no Authorization header (see the warning above)
  • OAuth 2.0 / OpenID Connect

The parameter panel below the combobox changes according to the selected mode. The dedicated panels documented below exist for Basic, Bearer Token, and OAuth 2.0 / OpenID Connect; for HTTP/gRPC these are the inline modes with full UI support. (For Kafka, the inline panel is the Kafka-specific control described in Kafka Authentication.)

Basic Authentication​

Problem it solves: The simplest HTTP authentication — a username and password sent as Authorization: Basic <base64>. Use it for APIs that protect endpoints with simple username/password credentials (server-to-server or internal tools).

Fields:

  • Username: — the user identifier
  • Password: — the password or secret (masked)
  • Preemptive Authentication: — toggle between "Send credentials with first request" and "Send credentials only when challenged"
note

For APIs that use a non-standard header convention, add the credentials as custom headers in the Headers tab instead, or use an API Key profile.

Bearer Token​

Problem it solves: Many modern APIs issue a static access token that you present in the Authorization: Bearer <token> header. Use this when you already have a token and do not need a full OAuth flow.

Fields:

  • Token: — the bearer token string (masked)
tip

Bearer tokens often expire. Reference environment variables (e.g. ${TOKEN}) instead of hardcoding tokens in saved requests. See Environments.

OAuth 2.0 / OpenID Connect​

Problem it solves: Delegated authorization and federated identity. Use it when the API is protected by an authorization server and you need Aethrix to obtain, cache, and (where possible) refresh access tokens — for web apps (Authorization Code + PKCE), machine-to-machine (Client Credentials), input-constrained devices (Device Code), or legacy first-party apps (ROPC).

The inline OAuth 2.0 panel is organized into sections:

Grant Type​

A pill bar selects the flow. Available flows:

Flow (UI label)When to use
Client CredentialsService-to-service / machine-to-machine. No user interaction.
Auth CodeWeb apps with a redirect/login flow. Supports PKCE and JAR.
ImplicitLegacy browser/SPA flow (token returned directly).
Device CodeInput-constrained devices; user authenticates on another device.
ROPCLegacy / first-party apps where the user supplies credentials directly.

Click Get Access Token to run the flow. When a token is valid, a masked token and a copy button are shown.

Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1. Prefer Auth Code with PKCE whenever possible.

Access & Endpoints​

  • Discovery Endpoint — paste an OpenID Connect discovery URL (e.g. https://server/.well-known/openid-configuration) and click Discover to auto-fill the endpoint URLs.
  • Scope — requested scopes (with suggestions from the provider's scope definitions).
  • Audience — the intended audience, when required.
  • Authorization Endpoint — (Auth Code / Implicit) where the user signs in and grants consent.
  • Token Endpoint — the URL that issues access tokens.
  • Refresh Endpoint — (Client Credentials / Auth Code / Implicit / ROPC) the URL used to refresh tokens.
  • Device Authorization Endpoint — (Device Code only).
  • Redirect URI — (Auth Code / Implicit) the callback URL; Aethrix handles this automatically and shows it read-only.

Client Identity​

  • Client ID — your application's client identifier.
  • Client Auth Method — how the client proves its identity to the token endpoint (client_secret_basic, client_secret_post, private_key_jwt, …).
    • When shared secret is selected, a Client Secret field appears.
    • When private_key_jwt is selected, a Private Key JWT section appears with a signing-key editor (PrivateKeyEditorControl) and a read-only Client Assertion Type. Optionally enable Use JAR (JWT Secured Authorization Request) to sign the authorization request as a request object (RFC 9101).

Resource Owner (ROPC only)​

  • Username — the resource owner's username (supports ${variable}).
  • Password — the resource owner's password (supports ${variable}).

Security Options​

  • Require PKCE — (Auth Code / Implicit) send a code_challenge (recommended) or disable it (not recommended).
  • Enable DPoP — attach a DPoP proof JWT to token requests (RFC 9449). (DPoP token binding is planned; standard bearer tokens are used today.)

Browser & Automation​

  • Automation Script — (Auth Code / Implicit / Device Code) run an automation script for login instead of manual browser interaction. When enabled you can set Headless Mode and edit the script via Edit automation script.

Additional Parameters / Auto-Managed Parameters​

  • Additional Parameters — free-form parameters sent with the request.
  • Auto-Managed Parameters — (Auth Code / Implicit) read-only Response Mode, Response Type, Redirect URI, State, and Nonce managed by the OAuth handler.

Token Management​

Obtained tokens are cached for the session and automatically included in requests. When a refresh token is available, Aethrix refreshes the access token on expiry. For a named OAuth2 profile, the credential summary shows OAuth2 — token valid until HH:mm:ss while the token is valid.

API Key (profile only)​

Problem it solves: Many REST APIs authenticate with a single API key rather than a user/password or OAuth flow. Aethrix supports two variants — sent as a request header or as a query parameter — and they are configured as authentication profiles (not inline).

To use an API key:

  1. Create a profile of type API Key (Header) or API Key (Query) in Environment Management → Credentials (see Creating and managing profiles).
  2. Select that profile from the Credential: dropdown.

The key is stored in the profile and applied automatically; there is no separate inline API-key panel.

Kafka Authentication​

Problem it solves: Kafka brokers are typically secured with SASL (and optionally TLS). Use this when testing or producing/consuming against a secured Kafka cluster.

For a Kafka operation, the Authentication tab shows the Kafka Authentication panel (always visible, independent of the profile dropdown):

  • Security Protocol: — Plaintext, Ssl, SaslPlaintext, or SaslSsl. When the protocol does not use SASL (Plaintext/Ssl), no credential fields are shown.
  • SASL Mechanism: — Plain, ScramSha256, ScramSha512, OAuthBearer, or Gssapi.
  • Username: / Password: — shown for Plain / ScramSha256 / ScramSha512.
  • Bearer Token: — shown for OAuthBearer.
  • SSL/TLS Certificates — CA Certificate:, Client Certificate & Key:, Key Password:, and Endpoint Identification: for TLS-secured connections.

The compatible Kafka profiles (Kafka SASL Plain / Scram 256 / Scram 512 / GSSAPI / OAuthBearer) also appear in the Credential: dropdown and can be reused across Kafka operations.

Client Certificate (mTLS)​

Problem it solves: Mutual TLS proves the client's identity with an X.509 certificate during the TLS handshake — before any HTTP headers are sent. Use it for APIs/gRPC services that require certificate-based client authentication, or for compliance/zero-trust scenarios.

The client certificate is configured separately from the credential/profile, via the Use client certificate (mTLS) checkbox at the bottom of the Authentication tab. Checking it reveals the Client Certificate: editor (PrivateKeyEditorControl).

Certificate sources​

The certificate editor's pill bar offers these key providers:

SourceDescription
PFX/P12 FileSelect a .pfx or .p12 file from disk, with an optional password.
PEM TextPaste a PEM private key (and certificate) directly.
JWKPaste a JWK JSON key.
StoreLook up a certificate from an X.509 store. Choose the Store (e.g. CurrentUser\My) and select a certificate, or paste its Thumbprint.
ProfileReference a stored credential profile by Profile name.

Click Test (in the editor) to validate that the certificate loads; the result is shown inline next to the button.

Variable substitution​

Certificate fields support ${ENV_VAR} substitution (e.g. the store thumbprint) for CI/CD pipelines.

Protocol support​

The mTLS client certificate is cross-protocol — it attaches to the underlying TLS configuration of:

  • HTTP/REST — the SslOptions of the HTTP handler
  • gRPC — the channel's TLS credentials
  • SOAP — the WCF certificate credential
  • Kafka — the client certificate/key in the SSL/TLS section

Per-certificate connection pooling​

Requests using the same client certificate reuse TCP connections (keyed by certificate), improving performance for repeated calls.

note

The Use client certificate (mTLS) option is independent of the Credential: dropdown. You can combine an mTLS certificate with a Basic/Bearer/OAuth2 profile, or use the certificate alone (with Anonymous selected).

Security Notes​

  • Credentials are stored in the active Environment; secrets entered inline are not persisted to the profile file.
  • OAuth 2.0 tokens are cached in memory for the session.
  • For CI/CD pipelines, prefer environment variables or encrypted environment files over stored credentials. See Encryption & Security for the encryption model.

See Also​

Last updated on