Beta

Create a tenant

A new tenant starts with its own users, OAuth settings, audit history and logs. You are its first Tenant Admin.

OAuth/OIDC in your tenant

Your tenant has its own OAuth configuration and discovery documents.

Tenant management

Open OAuth Management in the tenant sidebar. Clients registers applications with a stable client ID, display name, client type, redirect URIs, enabled status, assigned scopes, the restrictScopes setting, and a consent choice. Scopes defines the access names available within the tenant. Access Token Management configures token format, lifetime, claim mapping, issuance policy, client assignment, and confidential client secrets. ID Token Management configures ID token signing, lifetime, and the claims in ID tokens and UserInfo responses. Key Management generates and rotates JWT signing keys. Metadata Management edits endpoint paths and custom discovery fields.

BTL administrators use the same controls under BTL Admin, OAuth Management for BTL's own organization. These pages always apply to BTL and do not offer a tenant selector. BTL access and tenant access are authorized separately.

New clients start disabled. A blank client is also restricted to its assigned exclusive scopes; the presets for applications that sign users in turn that restriction off, so they can use common scopes such as openid. Client type records whether an application can protect credentials. A confidential client authenticates with a generated secret or with assertions signed by its own key; Client authentication in your tenant explains the methods and secret rotation. A confidential client that hosts an API can also be made a resource server, which lets it introspect access tokens issued to any client in the tenant. The saved client name appears on the consent page. Consent can be requested every time, remembered for approved scopes, or skipped for a trusted client. Users still sign in when consent is skipped. A public client cannot prove its identity, so skipping consent for one lets another application that uses its client ID receive an answer without the user being asked; the client editor warns about this. When you create a client, Start from can fill in the usual settings for a web application, single-page application, native or desktop application, or machine-to-machine service; every setting stays editable before you save. Flow Policy turns each grant, response type and response mode on or off independently, and a client can select only the choices Flow Policy allows. A client keeps choices that Flow Policy later turns off, but they are not used until Flow Policy allows them again. Flow Policy also sets the browser session and authorization code lifetimes within supported ranges.

Saving a client revokes the access and refresh tokens issued to it, its pending authorization codes and its remembered consent when the change affects what was granted: its type, flows, PKCE or consent setting, scopes, redirect URIs or token managers, or turning it off. A new name, a resource server change, or turning a client on revokes nothing. The client editor warns before a save that revokes.

In User Management, an administrator with the credential permission can set a tenant user's password. Share it privately. Setting a new password signs out that tenant user and revokes their existing OAuth tokens and pending codes. Tenant users do not use BTL administrator credentials.

Read the Scopes guide for configuration steps, access rules, and discovery behavior. Open Clients or open Scopes to manage a tenant you are authorized to access.

Token managers and defaults

Every client uses one access token manager and one ID token manager. In each management page, one enabled manager is marked Default. When you create a client, its manager selects start on the defaults, and you can choose another manager before saving. Choosing a manager other than the default, or changing a client's manager later, needs the assign permission for that kind of manager. Changing the default affects clients created afterwards; existing clients keep their manager. The default cannot be disabled or deleted until another manager becomes the default.

An access token manager can set the refresh inactivity lifetime from 60 seconds to 90 days. Each successful refresh starts that inactivity window again. The separate family absolute lifetime caps the whole connection from its first issue; refreshing cannot extend it. Use a dedicated manager and client when practicing a short expiry so other applications keep their existing policy.

Each manager lists the standard claims for its token, such as sub, aud, and exp, filled in with their protocol values. You can set your own value as text, an attribute, or a JavaScript expression, and omit optional claims. aud also accepts a list, and an ID token's audience must still include the client ID. The issuer is always the tenant URL. In ID tokens, nonce, at_hash, c_hash, and azp are set by the protocol and cannot be changed, because they protect client applications against replay and token substitution. So are iat, auth_time, and amr, which tell the application when and how the user signed in. In access tokens, client_id always names the client that requested the token, a custom scope may only leave granted scopes out, and an earlier exp also ends the token sooner for introspection and UserInfo. Required claims can be changed but not removed. Values are checked when a token is issued, and a value outside its allowed range stops issuance rather than producing a broken token.

Applications recognize a user by the issuer and sub together, so each sub value belongs to the first user or client that receives it and is never given to anyone else, even after that user is deleted. A setting that would give a value to someone else stops issuance with server_error, and the tenant's Audit and Logs record subject_in_use. A fixed text, or an attribute that can move between accounts such as the email address, therefore works for one user only. The sub row also offers the user ID with a fixed prefix or suffix, which stays different for every user.

Changing a claim changes what a token says, not how this service treats it. Expiry, revocation, granted scopes, introspection, and UserInfo always use the service's stored records.

OpenID Connect

Every tenant includes the built-in openid, profile, email, and offline_access scopes. Their names are fixed and they cannot be deleted, but their description and common or exclusive access can change. offline_access asks for a refresh token, so the consent page lists it, and consent remembered without it does not cover it. A client set to skip the consent page still shows it, every time, for a request with offline_access, because OpenID Connect Core section 11 asks for consent to offline access unless another basis is established. Tick Issue refresh tokens for offline_access without asking on such a client to declare that basis: the tenant runs the application for its own people. It is off by default, needs Skip consent page, and turning it off ends the refresh tokens the client holds. Never tick it for a third-party application. A client granted openid receives an ID token signed with a key published in the tenant's JWKS. A client's Sign ID tokens with setting (id_token_signed_response_alg) chooses the algorithm, and the newest active key of that algorithm signs; The ID token manager's key uses the key its ID token manager names. New clients start with RS256, the algorithm every OpenID Connect application must accept, and a client registered without naming one gets RS256 too. An ID token manager can use any active key. Discovery lists RS256 and every active key's algorithm, since a client may choose any of them. Your tenant always keeps an active RS256 key: the last one cannot be retired, and neither can the last active key of an algorithm a client chose. Profile claims appear only when their scope is granted, and each claim can go to the ID token, the UserInfo response, or both. A request with openid needs a response type that returns an ID token or a code, so token alone is refused.

The UserInfo endpoint, /oidc/userinfo by default, accepts an access token granted openid in the Authorization: Bearer header or a form body. Tokens in the query string are refused. Its sub is always the sub an ID token for the same sign-in carries, including after a refresh that returns no new ID token and for an access token returned by the authorization endpoint. Claims that belong only in a signed token, such as aud and exp, are left out. Each UserInfo read, and each refusal of a well-formed token, is recorded in the tenant's protocol Audit; a request with no token is in Logs only.

Some refusals can be repeated by anyone at no cost: an access token the tenant does not hold sent to UserInfo, or a password attempt that the wrong-password setting slows or locks. Audit keeps the first of these each minute (per tenant for unknown tokens; per account, limit and network for password attempts) and Logs count every one, so a flood cannot fill Audit. A refused token that the tenant still holds, such as a revoked or expired one, and a reused or expired password reset or unlock link are recorded each time against the person they belonged to, never as that person's action. The application always receives only invalid_token; the specific reason is visible only to administrators.

Tenant users confirm their email address when they register or from their Security page. With the email scope, the default ID token manager also sends email_verified, which is true only once the user has confirmed their current address. Every ID token issued for a signed-in user includes auth_time. The amr claim lists how the user signed in, for example pwd for a password, otp for a one-time or recovery code, our passkey value for a passkey, email for an email sign-in link, and mfa when two different kinds of factor were proved. Sign-in methods in tokens explains every value. When the method is not known, amr is left out.

Authorization requests accept nonce, prompt (none, login, consent, select_account, or create), max_age, login_hint, which only fills in the email field, and id_token_hint. max_age and prompt=login are met by a sign-in during the request, however long the user then spends on the consent page, and max_age=0 always asks the user to sign in. select_account shows the account the browser is signed in to, with a choice to use another. An id_token_hint must be an ID token this tenant signed for the client, sent as is or encrypted to one of your tenant's encryption keys; its expiry does not matter. If someone else is signed in, prompt=none returns login_required; without it the user is asked to sign in, and the application receives login_required if a different user does. With prompt=none, a login_hint email for another account returns login_required, recorded as login_hint_mismatch: a browser keeps one signed-in account at a time, so the hinted person would have to sign in. A parameter sent without a value counts as left out. A parameter sent twice, other than resource, is refused with invalid_request, sent back to the application when its client_id and redirect_uri each appear once and are valid. The registration parameter and WebFinger discovery are not supported. Pushed requests and signed request objects are explained in Pushed requests and request objects in your tenant. Authentication levels (acr_values), the claims parameter, pairwise subject identifiers, prompt=create and per-scope consent are explained in Authentication levels and claims in your tenant. UserInfo accepts any active access token that carries openid, whichever resource it is addressed to.

Protocol availability

The token endpoint supports authorization code redemption, client credentials and refresh, and the device authorization, CIBA, JWT bearer, token exchange and SAML 2.0 bearer grants, each when enabled by tenant and client policy. More grants, CIBA and approvals and the SAML bearer grant explain the others. A refresh token is issued only when the granted scopes include offline_access and both Flow Policy and the client allow the refresh token grant. Each access token manager sets a refresh token reuse grace from 0 to 60 seconds, 0 by default: within it, a client that lost a refresh response may present the same refresh token again and receive new tokens, recorded in Audit as a grace use; after it, or with 0, any reuse ends the whole sign-in. Each refresh returns a new refresh token, and the whole family ends at its access token manager's absolute lifetime, however often it is used. The authorization endpoint signs in tenant users, asks for consent according to the client setting, and returns a code, tokens, or both.

Implicit and hybrid response types are an ordinary tenant choice, off by default. They work only after a Tenant Admin allows the implicit grant and those response types in Flow Policy and on a client. Their tokens are returned in the fragment or by form post, never in the query string. Current OAuth security guidance (RFC 9700) advises against them because the tokens pass through the browser, so Flow Policy and the client editor show a warning while one is selected. An access token returned together with a code is revoked with the code's other tokens if the code is redeemed twice.

Both /.well-known/openid-configuration and /.well-known/oauth-authorization-server describe the selected tenant's issuer, common scopes, endpoint paths, and available public signing keys. Administrators can move endpoint paths within the tenant URL, but cannot change the issuer or well-known metadata URLs. Metadata Management can also publish informational fields, service_documentation, op_policy_uri, op_tos_uri, ui_locales_supported and claims_locales_supported, and the tenant's own fields whose names start with x_. Fields that describe protocol behavior come only from the service, so discovery never advertises something the tenant does not do.

Discovery documents and the JWKS may be cached by clients for up to five minutes. A newly generated key can take that long to reach every client, and a disabled key can keep verifying at clients that cached it for that long, so generate a key a few minutes before a manager starts signing with it.

Access tokens can be signed JWTs or opaque reference tokens. A client names the API a token is for with the resource parameter (RFC 8707), and the token's aud becomes that resource's audience; Resources in your tenant explains how. Without it, the token is addressed to the tenant's default resource, or to <issuer>/resource unless its access token manager sets its own aud. Confidential clients can introspect and revoke their own tokens. Public clients can revoke their own tokens by sending their client_id, but cannot introspect. A confidential client made a resource server can also introspect access tokens issued to other clients in the tenant, which is how an API validates opaque tokens: those addressed to the resources it is linked to, or, while it is linked to none, those addressed to no registered resource; refresh tokens stay private to the client that holds them. No client can revoke another client's token: such a request is refused with unauthorized_client, while an unknown or already invalid token still gets an empty success answer, so the response never confirms whether a value is a token. Introspection reports token_type Bearer for an access token and none for a refresh token. An endpoint URL in metadata is not a promise that every grant is available. Unimplemented protocol endpoints report their status rather than issuing credentials.

Browser and native applications

A browser application registered as a public client can redeem its code and revoke its tokens from its own page. The token and revocation endpoints let a browser read the answer to a public client's request when it comes from the origin of one of that client's redirect URIs, without cookies or other credentials. Responses to confidential clients, and introspection, are never readable from another site's page. The only other site allowed is this website itself, for the SCIM console in Docs and the request console on Lab pages, which send the credentials you type from your own browser.

A native application uses the system browser and a loopback redirect URI, such as http://127.0.0.1/callback. A loopback URI matches any port in the request, so the application can listen on whichever port is free (RFC 8252); the code must then be redeemed with the same port. Set the client's application type to native for a loopback redirect URI: a new tenant refuses one on a web application, as RFC 9700 section 2.6 asks, unless Flow Policy sets Loopback redirect URIs for web applications to Allowed. Lab tenants start with it allowed, so a learner's terminal can stand in for an application's server. Refusing them again waits until no web application registers one, and the authorization endpoint stops using any that remain. Every other redirect URI must match exactly. HTTPS addresses an application has claimed work like any other HTTPS redirect URI. A client whose application type is native may also register a private-use scheme such as com.example.app:/callback. A registered query string is kept exactly as registered, with the response added after it, so it cannot use the names the response adds, such as code or state.

Token endpoint answers

Refusals use the RFC 6749 error codes, each with a fixed error_description. Parameters a grant does not use, such as a scope sent with a code, are ignored. The client credentials grant cannot request openid, since there is no user, and is refused with invalid_scope. Two answers are not RFC 6749 refusals: a request over the tenant's rate limit receives temporarily_unavailable with HTTP 429 and Retry-After, and a problem on the server, such as a client without an enabled token manager, receives server_error with a reference_id that the tenant administrator can search for in Logs. When a grant has no scopes, the response leaves scope out.

We value your privacy

We use cookies and similar technologies to enhance your browsing experience, and analytics to understand our traffic. By clicking "Allow all", you consent to optional analytics. Cookie Policy

Documentation