Creating a client using the Vantage API

Create API clients programmatically when you need to automate provisioning — for example, as part of infrastructure-as-code or when integrating multiple apps at scale. Before creating a client, authorize in the Vantage API. For details, see Authentication.

Creating a client

Send a POST request with the Authorization: Bearer <access token> header to {baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/ with the following request body parameters:

Parameter	Description
`clientId`	The client’s identifier.
`clientName`	The client name (for example, the name of your app).
`allowOfflineAccess`	Whether a refresh token is generated along with the access token. The application can use the refresh token to renew the access token without user interaction. Default: false.
`allowRememberConsent`	Whether the user can choose to store consent decisions. Default: true.
`backChannelLogoutSessionRequired`	Whether the Backchannel Logout mechanism is required. Default: true.
`requireClientSecret`	Whether a client secret is required. Default: true.
`requireConsent`	Whether a consent screen is required. Default: false.
`allowNoPkce`	Whether the Authorization Code Flow without Proof Key for Code Exchange (PKCE) is allowed. Default: false, meaning only the Authorization Code Flow with PKCE is allowed.
`allowedGrantTypes`	The grant types the client can use.
`allowedCorsOrigins`	Whether the default cross-origin resource sharing (CORS) mechanism is used.
`allowedScopes`	The scopes transferred in the token. Must be an array containing exactly `"openid"`, `"permissions"`, and `"publicapi.all"`.
`postLogoutRedirectUris`	A list of allowed URIs to redirect to after logout.
`redirectUris`	A list of website or app URLs whitelisted for authorization token redirects. Prefixes are allowed — if a prefix matches, any URL under it is allowed. For example: `["https://myDomain.", "https://myApp.myDomain.com/oauth-signin.html"]`.
`accessTokenLifetime`	The time period during which an issued access token grants access to Vantage. Default: 24 hours.
`refreshTokenLifetime`	The absolute time period starting from the first access token’s issuance, during which the refresh token can be used to renew the access token. Default: 30 days.

When authenticating using Resource Owner Password Credentials (ROPC), set allowRopc to true. ROPC requires the user to send their credentials directly to the application, so use it only for trusted confidential clients.

Sample request

Linux or macOS
Windows (cmd)

curl --location --request POST '{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "{clientId}",
    "clientName": "{clientName}",
    "allowOfflineAccess": true,
    "allowRememberConsent": true,
    "backChannelLogoutSessionRequired": true,
    "requireClientSecret": true,
    "requireConsent": false,
    "allowNoPkce": true,
    "allowedGrantTypes": ["{allowedGrantTypes}"],
    "allowedCorsOrigins": ["{allowedCorsOrigins}"],
    "allowedScopes": ["openid", "permissions", "publicapi.all"],
    "postLogoutRedirectUris": ["{postLogoutRedirectUris}"],
    "redirectUris": ["{redirectUris}"]
  }'

curl --location --request POST "{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/" ^
  -H "accept: application/json" ^
  -H "Authorization: Bearer {token}" ^
  -H "Content-Type: application/json" ^
  -d "{\"clientId\":\"{clientId}\",\"clientName\":\"{clientName}\",\"allowOfflineAccess\":true,\"allowRememberConsent\":true,\"backChannelLogoutSessionRequired\":true,\"requireClientSecret\":true,\"requireConsent\":false,\"allowNoPkce\":true,\"allowedGrantTypes\":[\"{allowedGrantTypes}\"],\"allowedCorsOrigins\":[\"{allowedCorsOrigins}\"],\"allowedScopes\":[\"openid\",\"permissions\",\"publicapi.all\"],\"postLogoutRedirectUris\":[\"{postLogoutRedirectUris}\"],\"redirectUris\":[\"{redirectUris}\"]}"

The response contains a description of the created client.

Creating a secret

Each client can have multiple secrets. This lets the client start using a new secret when the current one expires, without deleting the old one. By default, a client secret expires after six months. Send a POST request with the Authorization: Bearer <access token> header to {baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/{clientId}/secrets/ with the following request body parameters:

Parameter	Description
`description`	A short description to help you tell secrets apart. Optional.
`startTime`	The secret start date.
`expiration`	The secret expiry date (between 1 day and 3 years). For example, `2021-09-07T13:03:38.380Z`. Defaults to exactly six months from the secret creation date.

Sample request

Linux or macOS
Windows (cmd)

curl --location --request POST '{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/{clientId}/secrets/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json-patch+json' \
  -d '{
    "description": "{description}",
    "startTime": "{startTime}",
    "expiration": "{expiration}"
  }'

curl --location --request POST "{baseUrl}/api/adminapi2/v2/tenants/{tenantId}/clients/{clientId}/secrets/" ^
  -H "accept: application/json" ^
  -H "Authorization: Bearer {token}" ^
  -H "Content-Type: application/json-patch+json" ^
  -d "{\"description\":\"{description}\",\"startTime\":\"{startTime}\",\"expiration\":\"{expiration}\"}"

The response contains the client secret (value) and its validity period (startTime, expiration).

The client secret value is only available at creation time. Store it in a secure location — later, you can only view the first three characters of the value (valueDisplay).

Managing Vantage API clients

Overview of API client management in your tenant

Creating, configuring, and deleting a Public API client

UI alternative — create and configure clients in the Vantage UI

Creating a tenant via the Vantage API

Programmatic tenant provisioning

Authentication

Sign-in flows and OAuth 2.0 / SAML 2.0 options

Tenant Admin Guide

Documentation Index