Neptune DXP Documentation
Neptune DXP - Open Edition · 25.0 MTS

OAuth Clients

With OAuth Clients, you create client credentials that other systems use to call this instance without a user session. A client exchanges its ID and secret for a short-lived token and calls any API as the service user bound to the client. Typical callers are agents on other instances that use this instance’s agents as A2A peers, and system integrations.

The list shows Name, Service User, Client ID, Enabled, and Created for every client.

Create a client

  1. In the Cockpit, go to the OAuth Clients tool and select Create.

  2. Enter a Name.

  3. Select the Service User the client acts as. The list only contains users with the API token enabled. To enable it, open the user in User tool, go to the API Token tab, and switch on Enable.

  4. Choose Create.

The dialog Client Credentials shows the Client ID, the Client Secret, and the Token URL. Copy credentials copies all three together with the grant type as JSON to the clipboard.

The client secret is shown only once. It cannot be retrieved later. To replace a lost secret, delete the client and create a new one.

The roles of the service user decide what the caller may do. Give the service user only the roles the integration needs, for example the role of the agent it is allowed to call.

Edit and revoke a client

Open a client to change its Name or switch Enabled off. The service user is fixed at creation. A disabled client cannot obtain new tokens; tokens already issued stay valid until they expire.

To revoke all tokens of a service user at once, generate a new API token for the user in User tool. Deleting the user deletes its clients.

Obtain a token

Callers send a client_credentials request to [PROTOCOL]://[HOST]/api/oauth/token. The client ID and secret go either in the body or in an HTTP Basic Authorization header.

POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=[CLIENT-ID]&client_secret=[CLIENT-SECRET]
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The token is valid for one hour and is sent as Authorization: Bearer [ACCESS-TOKEN] on any API call. Only the client_credentials grant is supported; there are no scopes.

Errors follow the OAuth 2.0 format. invalid_client means the ID or secret is wrong or the client is disabled. unauthorized_client means the service user no longer has the API token enabled.

To call another Neptune DXP - Open Edition instance with credentials created there, use the proxy authentication type Neptune DXP Service Account (OAuth 2.0).

Related topics