Authentication Guide
This guide explains how to obtain access tokens in the Marketplace edition.
Overview
Use one of two authentication flows depending on the purpose.
| Application | System Integration | |
|---|---|---|
| Authentication flow | Authorization Code (PKCE) | Client Credentials |
| Purpose | Employees sign in with their own accounts from external tools | Your company's systems use it server to server |
| Token retrieval | Sign in with a browser and obtain it through an authorization code | Obtain it directly with the service account credentials |
| Refresh token | Yes | No (obtain a new one after expiry) |
| Where to prepare | Authorization server console | Admin console |
For the preparation steps, see the API Setup Guide. For the detailed specification, see the Authentication API Reference.
Prerequisites
- The setup of the AGENTIC STAR environment purchased on the marketplace is complete
- Application: an administrator has opened the entrance for sign-in from an external tool and created an external tool client in the authorization server console (API Setup Guide — Creating an Application)
- System integration: a service account has been created in the admin console, and you have its
Client IDandClient Secret(API Setup Guide — Creating a System Integration)
Tokens and APIs are on different domains. Tokens are on the domain of the authentication service (or the external entrance of the authorization server), and APIs are on the domain of the external API. Both were decided by the administrator when building the environment.
Authorization Code Flow
An employee signs in with an external tool and obtains an access token and a refresh token through an authorization code. MCP-capable AI clients (such as Claude Code and Codex) perform these steps by themselves (AI Client Connection Guide (MCP)). To sign in from your own application, follow the steps below.
1. Authorization Request
Redirect the user in the browser to the authorization endpoint of the external entrance of the authorization server. PKCE (S256) is required.
GET https://<authorization-server-domain>/realms/<realm>/protocol/openid-connect/auth?
response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=http://localhost:8765/callback
&scope=openid
&state=STATE_VALUE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
| Parameter | Required | Description |
|---|---|---|
response_type | Required | Fixed to code |
client_id | Required | The ID of the client created in the authorization server console |
redirect_uri | Required | A redirect URI registered for the client |
scope | Required | Include openid |
state | Recommended | A random value against CSRF. Always check that the returned value is the same as the one in the request |
code_challenge | Required | The SHA-256 of code_verifier, base64url-encoded |
code_challenge_method | Required | Fixed to S256 |
2. User Authentication
On the sign-in screen of the authorization server, sign in with the same email address and password as for the Main Screen. Only approved users who have verified their email address can sign in (when the client was created by following the API Setup Guide).
3. Receive the Authorization Code
After sign-in, the browser is redirected to redirect_uri. The URL contains a temporary authorization code (code).
4. Exchange the Code for Tokens
Exchange the authorization code for an access token at the token endpoint. The client is public, so do not send client_secret.
curl -X POST https://<authorization-server-domain>/realms/<realm>/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "client_id=YOUR_CLIENT_ID" \
-d "code=AUTHORIZATION_CODE" \
-d "redirect_uri=http://localhost:8765/callback" \
-d "code_verifier=CODE_VERIFIER"
Use access_token in the response to call the API, and refresh_token to get a new one later.
5. Refresh the Token
When the access token expires, get a new one with the refresh token.
curl -X POST https://<authorization-server-domain>/realms/<realm>/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=YOUR_CLIENT_ID" \
-d "refresh_token=REFRESH_TOKEN"
Client Credentials Flow
Obtain an access token with the credentials of a service account created in the admin console. No user interaction is involved. Run the following request on the server side.
curl -X POST https://<auth-domain>/api/v1/oauth/token \
-u "<your-client-id>:<your-client-secret>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"
- Send the client authentication either with Basic authentication in the
Authorizationheader or withclient_idandclient_secretin the body, not both <auth-domain>is the domain of the authentication service of your environment (for example,auth.example.com)
Response example
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "openid profile email"
}
Wrong credentials return 401 Unauthorized ({"error": "invalid_client", ...}).
The earlier POST https://<auth-domain>/api/v1/auth/external-service-token (with client_id and client_secret in a JSON body) can still be used. Its response has success, access_token, token_type, expires_in, and scope.
Token Re-acquisition
The Client Credentials flow does not issue refresh tokens. When the access token expires (after the number of seconds in expires_in), run the same request again to obtain a new token.
Track the expiration and obtain a new token before it expires to avoid interruptions in API calls.
Scopes
The Marketplace edition applies no scope restrictions. Neither flow narrows the APIs by scope.
- With an application token, the user can do what the user is permitted to do. What can be done with projects depends on how the user participates in each project and on the organization operations role (User API Reference (Projects))
- The APIs that can be called with a system integration token are those in the System Integration API Reference
Using Access Tokens
Set the access token you obtained as a Bearer token in the Authorization header of API requests.
Authorization: Bearer <access_token>
The same format is used for all API endpoints. The API address is https://<your-domain>/api (<your-domain> is the domain of the external API).