Tenant configuration

Access configuration API

Configures Access, the tenant's OAuth / OpenID Connect server: web clients, API clients, scopes, identity providers, SAML service providers, web hooks, assurance levels and mobile app versions. It is the API behind most of Access admin.

https://{tenant-host}/oauth/api/v1/configurationAccess API client42 operations

Last checked against a live tenant: 28 October 2026checked live called on a tenantfrom source read in the service codenot confirmed not confirmed

When to use it

Create or change web clients (the M2M clients other service APIs need) from a pipeline.
Read a client's grant types, Default audiences and Default scopes when a service refuses its token.
Keep scopes, IdPs, SAML service providers and web hooks in code and apply them per tenant.

Connect

Base URL: https://{tenant-host}/oauth/api/v1/configuration
Client to create: Access admin → API clients → a client with the Access config API allowed (scope onegini_api_config). Not a web client: a web client sent here gets 401 invalid_credentials.checked live
Authentication: No token request. Send the API client's credentials on every call: HTTP Basic with the client ID and secret, or, with Private key JWT, Authorization: Bearer <signed JWT>.checked live
Private key JWT: Sign a fresh ES256 JWT per call: iss = sub = client ID, aud = https://{tenant-host}/oauth, exp about 60 s after iat, a random jti. Register the public key on the API client as a PEM (-----BEGIN PUBLIC KEY-----), not as a JWK.not confirmed
Allowed APIs: Each API is allowed per API client. An API client without this one gets 403 insufficient_permissions. The events and end-user APIs (onegini_api_events, onegini_api_end_user) are separate permissions.checked live

curl -s https://{tenant-host}/oauth/api/v1/configuration/web-clients \
  -u "$API_CLIENT_ID:$API_CLIENT_SECRET"

# With Private key JWT: a freshly signed JWT per call
curl -s https://{tenant-host}/oauth/api/v1/configuration/scopes \
  -H "Authorization: Bearer $CLIENT_ASSERTION"

Operations

Open an operation to see its parameters and code, and send it to your tenant. The API client needs the Access config API (onegini_api_config) allowed. Access's other APIs on the same host, such as /oauth/api/v1/events and the per-user sessions, tokens and devices APIs, need other permissions on the API client and are not listed here.

Connect to your tenant

Then open any operation below and send it.

Tenant hostToken, or a full Authorization value (Basic … / Bearer …)

This API doesn't take a client-credentials token from a web client. Get credentials as the Connect section says and paste them here; they stay in this tab only.

What trips people up

Web clients and API clients are not interchangeable

checked live

This API takes only an API client: a web client gets 401 invalid_credentials. The other service APIs take only a web client's token. An API client without this API allowed gets 403 insufficient_permissions.

access_token_expires_in is always required on create

checked live

The spec doesn't mark it required, but a web client create without it fails with 400 "Field [access_token_expires_in] must be a positive integer". With the authorization_code grant, access_grant_expires_in is required too.

Scope PATCH replaces the whole scope

checked live

Fields you leave out are cleared, descriptions included. Send the full scope with scope_id in the body. usage_limit: null is refused; send 0 for no limit. Web client PATCH is different: it keeps fields you leave out.

Reads are cached for about 2 minutes

checked live

After a PATCH or DELETE, a by-id GET can return the old version for about 2 minutes. Lists catch up sooner. Tokens reflect a client change at once: decode a fresh token's aud and scope to verify.

Default scopes over 1024 characters break the client

checked live

The PATCH succeeds, but the token endpoint then answers 500 to that client. Keep the client's Default scopes, joined with spaces, within 1024 characters, and move the rest to Additional scopes.

hashed_client_secret must be in PHC form

checked live

Send bcrypt as $bcrypt$c=10$<salt>$<hash> in standard base64. The usual $2a$ / $2b$ / $2y$ form fails with 400 "Field [hashed_client_secret] has an invalid format".

public_jwk takes a PEM key

not confirmed

For a Private key JWT API client, public_jwk must be a PEM public key. A JWK is refused with 400 "Provided key type not supported". With CLIENT_SECRET_BASIC, the create needs the secret, or it fails with 400.

Lists come wrapped in result

checked live

The list endpoints answer {"result": [...]}. An empty tenant setting is {"result": []}, not a 404.

Errors

Access answers authentication problems before it looks at the request.

400		Validation failed. The message names the field, e.g. "Field [access_token_expires_in] must be a positive integer".
401	invalid_credentials	The caller is not an API client, or its credentials are wrong. A Private key JWT with the wrong key, client ID or `aud` is refused with 401 too.
403	insufficient_permissions	"The provided API client is not allowed to use this API." Allow the API on the API client.

When a call fails

Reply	Means	What to change
The service answers 401	The token lacks this service's audience, or it expired.	Add the audience to the client's Default audiences (Access admin → Web clients → the client), then get a new token.
The service answers 403 and the token has the audience	A scope the operation needs is missing.	Add one of the operation's scopes to the client's Default scopes. Use the scope names your tenant lists under Access admin → Scopes.
Token endpoint: 401 invalid_client	Unknown client ID or wrong secret.	Check the client ID and paste the secret again.
Token endpoint: 400 unauthorized_client	The client may not use client credentials.	Add the grant type Client credentials to the web client.
Token endpoint: 400 invalid_request about an audience	You asked for an audience the client doesn't have.	Add it to Default audiences, or stop asking for it.
Token endpoint: 500 right after scopes were added	The client's Default scopes, joined with spaces, are over about 1024 characters.	Move scopes to Additional scopes and request them per call, or split the work over two clients.
{"code":"not_found","message":"The requested location was not found"}	That service isn't deployed on this tenant.	Nothing to change in the client. Ask whoever runs the tenant.

Two kinds of client exist in Access. Service APIs like this one take a web client with the Client credentials grant. Access's own configuration API takes an API client: a web client sent there gets 401 invalid_credentials.