Add an authentication profile

Save a bearer token, user name and password, API key or OAuth client once on a project.

In short

A profile stores one credential on a project, encrypted, so requests can use it without anyone seeing it. It can be a bearer token, a user name and password, an API key, an OAuth client, or a login request that fetches a token for you.

Before you start

• Who: making, replacing, connecting and deleting profiles needs Manage on the project. People who run a request use the credential without seeing it.
• Plan: every plan. A login-request profile sends a request each time it refreshes, and that counts toward your allowance; Free monitors cannot use one.
• First: for a login-request profile, save the login request in the project first.

Steps

1. Open "Project settings", "Authentication" and choose "New profile".
2. Choose the kind and fill in its fields (see the table).
3. For Authorization code with PKCE, press "Connect" and sign in once in the popup.
4. Choose it as the project's "Default profile" so every request inherits it.

Result: requests send the credential; the saved secret reads "Saved" and is never shown again.

Sign in with a login request

1. Save the login request in the project and check that it answers with a token.
2. Press "New profile" and set "Kind" to "Login request".
3. Choose the "Login request", and give the "Token path" - where the answer keeps the token, as a JSONPath such as $.access_token.
4. If the answer says when the token expires, give the "Expires-in path" (seconds from now, a Unix time or a date). Otherwise give a "Token lifetime" between 30 seconds and a day; without either, 15 minutes is used.
5. Change the "Prefix" if the API does not use Bearer.

{{brand}} keeps the token encrypted until it is about to expire, then runs the login request again by itself. A suite or a busy monitor signs in once, not once per request.

Each sign-in is a request A refresh sends one request that counts against your plan, and a monitor's estimate shows the sign-ins it will make. A login request cannot itself sign in with a login-request profile, and Free monitors cannot use one.

Good to know

• "Replace" opens an empty field; leaving it empty keeps the saved secret.
• A profile keeps the kind it was created with. To switch kinds, create a new profile.
• If an API echoes a credential back, the answer shows [REDACTED].
• A quick request's credentials stay in that browser tab for that one request.

Do not paste long-lived secrets into saved headers Every project member can see a saved request's headers unless you use a profile.

If something goes wrong

• A profile cannot be deleted: the default, an environment or a request still uses it. Switch those first.
• 401 and 403 answers: most come from an expired token. Replace it and send again.
• "Enter the client secret again to change the token URL.": a saved secret never goes to a new address without it.
• A login-request profile gets no token: check the Token path against the login request's answer.
• "Give the profile a name." and "This project already has an authentication profile with that name.": choose another name.
• "A profile keeps its kind. Create a new profile for another kind of authentication."
• "A Basic user name cannot contain a colon.": remove it.
• "Name the key with letters, digits, dashes, dots or underscores - for example X-Api-Key or api_key."
• "Say where the token is in the answer, for example $.access_token." means the "Token path" is empty. A message such as "The login answer has no token at $.access_token." means that path is wrong: correct the "Token path".
• "The login request did not answer with JSON, so there is no token to read.": the login must answer with JSON.
• "A login request cannot sign in with a login-request profile itself. Give it another profile or none."
• "A token can last from 30 seconds to a day.": change the "Token lifetime".
• "Remove this profile from project, environment, and request authentication settings first.": switch those to another profile, then delete it.
• "Connect this OAuth profile before running requests." and "OAuth session expired or was already used.": press "Connect" again.

Related

• /help/api-testing/authentication
• /help/api-testing/variables