Authentication Profiles: Choose and Configure a Method
Most APIs refuse a request that does not prove who is calling. In Shift-Left API you describe how to prove it once, in an authentication profile, and every test, pack, workflow and performance run in the project uses it.
Applies to: All editions (Free: up to 3 profiles per project; Professional, Trial and Enterprise: unlimited) · Web app and Desktop app · Access to the project's settings
Overview
Most APIs refuse a request that does not prove who is calling. In Shift-Left API you describe how to prove it once, in an authentication profile, and every test, pack, workflow and performance run in the project uses it. You never paste a token into individual tests.
A profile holds one authentication method (API key, Basic, Bearer, Digest, NTLM, OAuth 1.0a, OAuth 2.0, Hawk, JWT Bearer, AWS Signature v4 and so on), its settings, and its secrets. You tie a profile to an environment, so the same tests send staging credentials to staging and production credentials to production.
This article explains how to create a profile, how Shift-Left API decides which profile a run uses, and what every method's fields mean. Two methods have their own articles because they involve signing in: OAuth 2.0 Sign-In and Sign In With Steps.
Key concepts
| Term | Meaning |
|---|---|
| Authentication profile | A named, reusable set of credentials for one project. |
| Method | How the credential is sent: a header, a query parameter, a signature, a client certificate, or a token that Shift-Left API obtains for you. |
| Environment | The environment a profile belongs to (set in the profile's Settings step). |
| Active | The profile that owns an environment. Only one profile per environment is active at a time. |
| Default profile | The fallback used when no profile is active for the environment. It is also pre-selected for new test cases. |
| Additional Headers | Extra headers the profile sends along with its credential. |
Before you begin
- Open the project and go to Project Settings, then the Authentication Profiles tab.
- Have the credentials from the API's owner: key names, URLs, client IDs, and the secret values.
- On the Free edition, a project can hold up to 3 profiles. The New Profile button is disabled when you reach the limit.
- If you want tests to read secrets from HashiCorp Vault, AWS Secrets Manager or Azure Key Vault, an administrator must connect one first (see Keep secrets in a secret manager).
Step 1 — Start a new profile
- On the Authentication Profiles tab, click New Profile (or Create Profile if the project has none yet).
- In Basic Info, enter a Profile Name, for example
Orders API – Staging. - Optionally add a Description and Tags. Press Enter after each tag.
- Click Next.
Step 2 — Choose and configure the method
- In the Authentication step, select a card under Authentication Method.
- Fill in the fields under Configuration. The method reference below explains each one.
- Optional: click Load Sample Configuration to see a filled-in example, then replace the values with your own.
- Optional: under Additional Headers, click + Add Header to send extra headers with every request, such as
X-Tenant-Id. Headers set on an individual test override these. - Click Next.
Tip: Secret fields are masked. Use the eye icon to check what you typed before you save.
Step 3 — Tie the profile to an environment
- In the Settings step, choose the Environment this profile is for.
- Select Set as default profile if this profile should be the project's fallback and be pre-selected for new test cases. A default profile is always active for all environments.
- Leave Profile is active selected so the profile can be used.
- Click Next.
Step 4 — Test and save
- In Test & Save, check the Configuration Summary.
- Optional: enter a Test Endpoint (Optional) such as
/api/health. If you leave it empty, Shift-Left API tries common endpoints on its own. - Click Test Authentication and read the result.
- Click Save Profile.
You can test a saved profile at any time: on its card, click the Test Profile icon, enter a Test URL, and click Run Test. A result of Authentication test successful means the API answered with a 2xx or 3xx status. Authentication test failed: the API answered 401 means the request went out but the API refused the credential.
Step 5 — Make the profile the one a run uses
On each profile card you can Edit Profile, Test Profile, see Usage, Duplicate, Activate or Deactivate, and Delete Profile. The status badge reads Default, Active or Inactive for the project's current environment.
When a test runs, Shift-Left API picks the profile in this order and writes its choice to the run log (for example, "Using active profile for Staging: Orders API – Staging (oauth2)"):
| Order | Source | How you set it |
|---|---|---|
| 1 | The profile chosen on the test itself | Test editor, Authentication Profile section |
| 2 | The profile active for the run's environment | Activate on the profile card |
| 3 | The most recently updated profile whose environment matches | The profile's Environment setting |
| 4 | The default profile | Set as default profile |
| 5 | No profile | The test's own settings only |
A test set to No Profile ("Use individual test settings only") skips profiles entirely.
Method reference
Each method below lists its fields as they appear in the dialog, and where Shift-Left API places the credential on the request. Methods marked "signed at send time" are computed over the final URL and body, just before the request leaves.
No Authentication
Sends nothing. Use it to switch a project or environment off authentication on purpose.
API Key
| Field | What to enter |
|---|---|
| Key Name | The header or parameter name, for example X-API-Key. |
| Key Value | The key. Encrypted. |
| Location | Header or Query Parameter. |
Sent as a header, or appended to the query string when the request is sent. Example: Key Name X-API-Key, Location Header, value ak_live_... → X-API-Key: ak_live_....
API Key + Bearer Token
For APIs that need both an API key and a bearer token on every request. The key is sent on every test request (in the header or query you choose) alongside the Authorization token. Choose a Token Source:
- Use Bearer Token directly: paste a Bearer Token and choose Bearer Prefix.
- Fetch token from URL: Shift-Left API also sends the key to the Token Endpoint and uses the token it returns.
| Field | What to enter |
|---|---|
| API Key Name | Header or query parameter name for the key. |
| API Key | The key. Encrypted. |
| API Key Location | Header or Query Parameter. |
| Token Endpoint | The URL that returns the token. |
| Token Expiry (seconds) | Used when the response does not state an expiry. Default 60. |
| Refresh (sec) | Fetch a new token this many seconds before expiry. Default 10. |
| Bearer Prefix | Yes (add "Bearer " prefix) or No (just the token). |
The token goes in the Authorization header. Shift-Left API reads access_token (or token.access_token) and common expiry fields from the response.
Basic Authentication
Username and Password (encrypted). Sent as Authorization: Basic <base64 of username:password>.
Bearer Token
Choose a Token Source:
- Use Bearer Token directly: paste the Bearer Token. It is sent as
Authorization: Bearer <token>and is never renewed. - Fetch token from URL: Shift-Left API calls a token URL and caches the result.
| Field (Fetch token from URL) | What to enter |
|---|---|
| Token URL | The URL that returns a token. |
| HTTP Method | GET (default) or POST. |
| Request Headers (JSON) | Headers for the token request. |
| Query Parameters (JSON) | Query parameters for the token request. |
| Request Body (JSON) | Body for a POST, for example your login fields. |
| Token JSON Path (Optional) | Where the token is, for example token.access_token. |
| Expiry JSON Path (Optional) | Where the expiry is, for example expires_in. |
Important: The token request's headers and body are not treated as secret fields. Do not type a password into Request Body (JSON). Use a project variable or a secret reference instead, or choose a method that stores the password encrypted, such as Sign In With Steps.
OAuth 2.0
Choose an OAuth Flow: Authorization Code (sign in with browser), Client Credentials (app only, no user), Device Code (sign in with a code), Password Grant (username + password), or Implicit (legacy — paste a token). The fields change with the flow.
| Field | Used by | What to enter |
|---|---|---|
| Client ID | All flows | Issued by your identity provider. |
| Client Secret | Required for Client Credentials; optional otherwise | Encrypted. Leave blank for a public (PKCE) client. |
| Token URL | All except Implicit | The provider's token endpoint. |
| Authorization URL | Authorization Code | The provider's sign-in page. |
| Device Authorization URL | Device Code | The provider's device-code endpoint. |
| Username / Password | Password Grant | The resource owner. Password encrypted. |
| Client Authentication | All except Implicit | Send as Basic Auth header or Send as request body. |
| Scopes | All | Space-separated. Add offline_access to get a refresh token. |
| Additional Authorization Parameters (JSON) | Authorization Code | Extra sign-in parameters, for example {"prompt": "select_account"}. |
| Additional Token Request Headers (JSON) / Additional Token Request Body (JSON) | All except Implicit | Provider-specific extras, such as audience. |
| Token Revocation URL | Authorization Code, Device Code | Revokes the refresh token when you sign out. |
| Access Token | All | Optional pasted token. It expires and is never renewed. |
The token is sent as Authorization: Bearer <token>. Client Credentials and Password Grant fetch tokens on their own and cache them until they expire. Authorization Code and Device Code need one sign-in; see OAuth 2.0 Sign-In. Fill in for a provider (optional) pre-fills the URLs for Microsoft Entra ID, Okta, Auth0, Keycloak and Google.
OAuth 1.0a
Signed at send time, over the exact URL (and a url-encoded form body).
| Field | What to enter |
|---|---|
| Signature Method | HMAC-SHA1 (default), HMAC-SHA256, HMAC-SHA512, RSA-SHA1, RSA-SHA256, RSA-SHA512 or PLAINTEXT. |
| Consumer Key | Required. |
| Consumer Secret | For HMAC and PLAINTEXT. Encrypted. |
| Private Key (PEM) | For the RSA methods, instead of the consumer secret. Encrypted. |
| Access Token, Token Secret | Optional. Leave both empty for two-legged OAuth. Encrypted. |
| Callback URL, Verifier | Optional. Sent as oauth_callback and oauth_verifier (the verifier is encrypted). |
| Realm, Version | Optional. Version defaults to 1.0. |
| Include Body Hash | Also signs a hash of a request body that is not a form (oauth_body_hash). |
| Add Auth Data To | Request Headers (an Authorization: OAuth … header, the default), or Request Body / Request URL: the oauth_* parameters are added to a url-encoded form body, otherwise to the URL. |
AWS Signature v4
| Field | What to enter |
|---|---|
| Access Key ID | For example AKIA.... |
| Secret Access Key | Encrypted. |
| AWS Region | For example us-east-1. |
| AWS Service | For example execute-api, s3. |
| Session Token (Optional) | For temporary credentials. Encrypted. |
Signed at send time over the exact URL and body. A SOAP request cannot be signed with AWS Signature v4, because the envelope is built after authentication is applied; the run log warns you and the request is sent unsigned.
Custom Header
Header Name and Header Value (encrypted). Sends one fixed header, for example X-Auth-Token: ....
Query Parameter
Parameter Name and Parameter Value (encrypted). Appended to every request URL when it is sent, for example ?api_key=....
Mutual TLS (mTLS)
Paste the Client Certificate (PEM) and Private Key (PEM). The private key is encrypted and never sent back to the browser. The server, or the local runner (Agent), presents the certificate when a test runs, over HTTPS only. A plain HTTP request is sent without it, and the run log says so.
Hawk Authentication
Hawk Auth ID, Hawk Auth Key (encrypted) and Algorithm (SHA-256 or SHA-1). Signed at send time into the Authorization header.
Optional, as in Postman: Include Payload Hash also signs a hash of the request body and its content type, so the server can tell the body was not changed; ext carries application data in the signature; app and dlg name an application and the application that delegated access. A SOAP body cannot be hashed (the envelope is built after authentication is applied); the run log says so and sends the header without a hash.
JWT Bearer
Shift-Left API can sign a JSON Web Token for you, the way Postman's JWT Bearer does, or send one you paste.
| Field | What to enter |
|---|---|
| Token | Sign a new token for every request (default) or Use a token I paste. |
| JWT | The pasted token. Encrypted. It stops working when it expires. |
| Algorithm | HS256/384/512 (a shared secret), RS256/384/512 or PS256/384/512 (an RSA private key), ES256/384/512 (an EC private key). |
| Secret | For HS algorithms. Encrypted. Choose Secret is Base64 encoded: Yes when you were given the key as Base64. |
| Private Key (PEM) | For RS, PS and ES algorithms. Encrypted. |
| Payload (JSON) | The claims, for example {"sub": "{{USER_ID}}", "aud": "orders-api"}. Project variables are filled in when the request is sent. |
| Extra JWT Headers (JSON) | For example {"kid": "key-2026"}. alg and typ are set for you. |
| Expires In (seconds) | Optional. Adds iat (now) and exp (now plus this many seconds) unless the payload sets them. |
| Add Token To | Request Header or Query Parameter. |
| Header Prefix | Written before the token, Bearer by default. Leave it empty to send the bare token. |
| Query Parameter Name | When the token goes in the query. Default token. |
A signed token is made fresh for every request, so a short expiry never runs out in the middle of a run. A JWT profile saved before this option existed keeps sending Authorization: JWT <token>; open it and set Header Prefix to Bearer if your API expects that.
Cookie / Session
Paste a Cookie Header, for example AppServiceAuthSession=... copied from your browser's developer tools. Encrypted. Sent as the Cookie header. It stops working when the real session ends.
Cookie Login Flow
Shift-Left API calls a login endpoint, captures the cookies it sets, and reuses them.
| Field | What to enter |
|---|---|
| Login URL | The login endpoint: a full address, or a path such as /api/login, which is added to the project base URL for the environment. The desktop agent needs the full address. |
| Login HTTP Method | POST (default), GET or PUT. |
| Login Request Headers (JSON) | Headers for the login call. Not encrypted, so avoid putting secrets here. |
| Login Request Body (JSON) | For example {"username": "user", "password": "{{PASSWORD}}"}. Encrypted. |
| Follow Login Redirects | Follow 3xx redirects and collect cookies across them. |
| Session Cache TTL (seconds) | How long to reuse the session. Default 900. |
| CSRF Token Source, CSRF Token Path, CSRF Header to Send | If the API needs an anti-CSRF token, where to read it and which header to echo it on. |
Sign in with steps
For APIs that sign in with several calls, such as a login followed by a one-time code. See Sign In With Steps.
NTLM Authentication
For Windows-integrated APIs (IIS, SharePoint, on-premises services). Enter the Username and Password (encrypted), and optionally the Domain and Workstation. A username written CONTOSO\jsmith or jsmith@contoso.local carries its own domain.
Each request is sent once; when the server answers 401 offering NTLM (or Negotiate), Shift-Left API answers the Windows challenge on the same connection and the request goes through (NTLMv2). An endpoint that needs no credentials is called once, as normal. Works for REST, GraphQL, JSON-RPC and SOAP, on the server and the desktop agent. Performance runs cannot answer the challenge and warn you before the run.
Digest Authentication
Enter a Username and Password. Each request is sent once without credentials; when the API answers 401 with a Digest challenge, Shift-Left API sends it again with the answer. MD5, MD5-sess and SHA-256 with qop=auth are supported, on the server and the desktop agent, for REST, GraphQL and JSON-RPC. SOAP calls are not answered yet (the run log says so).
Keep secrets safe
- Every secret field (passwords, client secrets, keys, tokens, the mTLS private key, pasted cookies) is encrypted at rest.
- Tokens that Shift-Left API obtains by signing in stay on the server. They are never shown in the browser.
- When a test runs on the local runner (Agent), the Agent receives what it needs for that run. For a signed-in profile it receives a live access token only, never the refresh token.
- The Project Assistant never accepts a secret typed into chat (see below).
Keep secrets in a secret manager
On the Trial and Enterprise editions, an administrator can connect HashiCorp Vault, AWS Secrets Manager or Azure Key Vault under Settings → Integrations → Secret Managers, then turn on Enable Secret Managers. Secret managers are off until an administrator turns them on. You can then put a reference such as secretref://<providerId>/<path>#<field> in a test's headers, query parameters or body, or in an OAuth 2.0 profile field, instead of the secret itself. Shift-Left API resolves it in memory just before the request is sent.
Use profiles in tests, packs, workflows and performance runs
- Tests: in the test editor, the Authentication Profile section lets you pick a profile, No Profile, or let the environment decide. Advanced: Override with custom authentication replaces the profile for that test only.
- Packs: in the pack wizard's execution preferences, turn on Override and choose an Authentication Profile for every test in the pack, or click Auto-pick default.
- Workflows: authentication is not chosen at pack level. Each Test node uses its own project's profile for the run's environment, then that project's default.
- Performance runs: requests are built with the same authentication as functional runs, and signed-in profiles keep a valid token during long runs. A signed request (AWS Signature v4, OAuth 1.0a, Hawk, a signed JWT) is computed once, not per request; NTLM cannot be used in a performance run (you are warned when the plan is built); and a scenario that uses a client certificate runs from the server only. See Performance Testing.
Configure it with the Project Assistant
You can ask the Project Assistant to set up a profile, for example "Set up OAuth 2.0 client credentials for staging with token URL https://login.example.com/token and scope orders.read". It fills in the method's settings (URLs, client ID, scopes, header names, region) and can start a browser or device sign-in. It refuses to take a secret in chat, by name, because a secret typed into a conversation stays in the transcript. Instead it opens the Authentication screen with the missing field marked so you can paste the secret there.
Troubleshooting
| Symptom | Why it happens | What to do |
|---|---|---|
| Every test fails with 401 | The profile was not applied, or its credential is wrong or expired. | Open a failed run's log and find the "Using profile…" line. If none is there, activate a profile for that environment or set a default. Then use Test Profile against a known endpoint. |
| 401 only in one environment | A different profile is active there. | Check the badge on each card for that environment and Activate the right one. |
| 403 with an HTML page in the response | A gateway or sign-in page answered, not the API. | Check the environment's base URL and any network allow-list. Run analysis labels this as an environment issue. |
| "Assigned auth profile '…' does not exist" | The test points at a deleted profile. | Choose another profile in the test's Authentication Profile section. |
| "…is not available in this project" | The assigned profile is disabled or belongs to another project. | Activate it, or pick a profile from this project. |
| Test passes, runs fail with "Sign-in expired" | The OAuth 2.0 or step sign-in expired or was revoked. | Open the profile and sign in again. |
| AWS-signed SOAP calls are refused | SOAP cannot be SigV4-signed. | Use another method for that service. |
| mTLS certificate not presented | The request used plain HTTP. | Use an https:// base URL. |
| Digest-protected API returns 401 | Wrong username or password, an unsupported challenge (the run log names it), or a SOAP call. | Check the credentials and the run log. |
| NTLM-protected API returns 401 | The run log says "the server refused these credentials" (wrong username, password or domain) or that the server sent no challenge (it wants another scheme, such as Kerberos only). | Check the domain (try DOMAIN\user) and the run log. NTLMv1-only servers are not supported. |
| JWT refused after upgrading | An older JWT profile sends the JWT prefix. | Set Header Prefix to Bearer. |
Best practices
- Create one profile per environment and Activate it, rather than editing one profile back and forth.
- Use a dedicated test account for credentials, never a person's own account.
- Prefer methods that renew themselves (OAuth 2.0, Sign in with steps, token URLs) over pasted tokens.
- Name profiles after the API and environment so the run log is easy to read.
- Check Usage before deleting or changing a profile.
FAQ
Can one test use a different profile from the rest of the project? Yes. Choose it in the test's Authentication Profile section. That choice wins over environment and default profiles.
Why can't I deactivate a profile? The project's default profile cannot be deactivated. Make another profile the default first.
Does duplicating a signed-in profile copy the sign-in? No. A duplicate must be signed in on its own.
Are secrets visible to other project members? Secret fields are stored encrypted and shown masked. Anyone who can edit the profile can replace them.
Related articles
- Project Settings: Environments and Auth
- OAuth 2.0 Sign-In: Browser and Device Code
- Sign In With Steps
- Test Run
- Project Assistant Overview
- Performance Testing
For administrators (self-hosted installations)
| Setting | Default | What switching it does |
|---|---|---|
SECRET_MANAGERS_ENABLED | off | Fallback for the Enable Secret Managers switch when it has not been set on the screen. |
OAUTH_TOKEN_CACHE_ENABLED | on | false fetches a new OAuth 2.0 token for every request instead of caching it. |
Previous
Project Settings: Environments and Auth
Product documentation
Next
OAuth 2.0 Sign-In: Browser and Device Code
Product documentation
Related articles
- Create Your First Project in Shift-Left API · Product documentation
- Project Operations: Import API Definitions · Product documentation
- Managing Projects and Endpoints · Product documentation
- Project Settings: Environments and Auth · Product documentation
- OAuth 2.0 Sign-In: Browser and Device Code · Product documentation
- Sign In With Steps: Login, One-Time Code, Token and Refresh · Product documentation
Next steps
- Getting started · Install + connect your spec
- Configuration fundamentals · Stabilize runs
- Initial configuration · Users, licensing, projects
- Release notes · Updates and fixes
Still stuck?
Tell us what you’re trying to accomplish and we’ll point you to the right setup—installation, auth, or CI/CD wiring.