Skip to main content

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.

ApplicationSystem Integration
Authentication flowAuthorization Code (PKCE)Client Credentials
PurposeEmployees sign in with their own accounts from external toolsYour company's systems use it server to server
Token retrievalSign in with a browser and obtain it through an authorization codeObtain it directly with the service account credentials
Refresh tokenYesNo (obtain a new one after expiry)
Where to prepareAuthorization server consoleAdmin 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 ID and Client 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
ParameterRequiredDescription
response_typeRequiredFixed to code
client_idRequiredThe ID of the client created in the authorization server console
redirect_uriRequiredA redirect URI registered for the client
scopeRequiredInclude openid
stateRecommendedA random value against CSRF. Always check that the returned value is the same as the one in the request
code_challengeRequiredThe SHA-256 of code_verifier, base64url-encoded
code_challenge_methodRequiredFixed 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
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
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
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 Authorization header or with client_id and client_secret in the body, not both
  • <auth-domain> is the domain of the authentication service of your environment (for example, auth.example.com)

Response example

JSON
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 86400,
"scope": "openid profile email"
}

Wrong credentials return 401 Unauthorized ({"error": "invalid_client", ...}).

The earlier token endpoint

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.

Best Practice

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).