Console Setup Guide
This guide explains how to create an application (client) in Console (admin panel) and configure the authentication information and scopes required for API usage.
Overview
To use AgenticStar's API, you must first create an application (client) in Console. Clients have two authentication patterns depending on the use case, which you select during creation.
- Ability to log in to Console (developer role or higher)
- Permission from the tenant administrator to use the API
For details, see Authentication Guide.
Selecting Client Type
The client's authentication pattern cannot be changed after creation. Select the appropriate type for your use case.
| Authorization Code (AC) | Client Credentials (CC) | |
|---|---|---|
| Use Case | Applications where end users log in via a browser | Server-to-server communication or batch processing where users are not involved |
| Authentication Flow | Authorization Code (+ PKCE) | Client Credentials |
| Token | Access token + refresh token | Access token only |
| Subtype | Confidential (with secret) / Public (PKCE only) | Confidential only |
| Tenant Requirement | Can be created for all tenants | Enterprise tenants only (cannot be created for SaaS tenants) |
If you use a SaaS tenant, the authentication pattern selection is not displayed, and AC (Authorization Code) is automatically applied. If you need a CC client, contact your tenant administrator.
AC Client (Authorization Code)
This is for applications where end users log in via a browser. Users go through tenant selection → login → authorization screen, after which an access token is issued.
Difference Between Confidential and Public
Confidential
For server-side applications. Used in environments where Client Secret can be stored securely. client_secret is required when making requests to the token endpoint.
Public
For SPAs (Single Page Applications) and mobile applications. Used in environments where Client Secret cannot be stored securely. PKCE (S256) is mandatory and provides protection through challenge verification using code_verifier / code_challenge.
Steps to Create an AC Client
Start creation by clicking "New Create" from the "Applications" menu in Console.
1. Enter Basic Information
| Item | Required | Description |
|---|---|---|
| App Name | ✓ | Display name of the application (max 256 characters). Also displayed on the user authorization screen. |
| Logo | ✓ | Logo image of the application. Displayed on the authorization screen and app list. |
| Overview (Brief Description) | ✓ | Concise description within 50 characters. Displayed on app list cards. |
| Detailed Description | ✓ | Detailed description of the application. Displayed on app detail pages. |
| Support URL | URL of support page. | |
| Privacy Policy URL | URL of privacy policy. Displayed on the authorization screen. | |
| Terms of Use URL | URL of terms of use. Displayed on the authorization screen. |
2. Select Publication Status
Set the publication scope of the application. Options vary by tenant type.
| Status | Available | Description |
|---|---|---|
| Development | SaaS / Enterprise | Under development. Available only to creator. Default at new creation. |
| Public | SaaS | Published to all users of the SaaS tenant. |
| Private | Enterprise | Limited publication to users within the Enterprise tenant. |
3. Technical Configuration
| Item | Required | Description |
|---|---|---|
| Client ID | — | Auto-generated UUID. Cannot be changed. Copy and use after creation. |
| Client Type | ✓ | Select Confidential or Public. Cannot be changed after creation. |
| Redirect URIs | ✓ | Register one or more redirect destination URLs after authorization completion. Validation is exact match, so enter the precise URL. |
| Web Origins | ※ | Required only for Public clients. Register origin URLs permitted by CORS. For Confidential clients, it is auto-configured and not displayed. |
Redirect URI is validated by exact match for security. It is recommended to register both development environment (http://localhost:3000/callback) and production environment (https://yourapp.com/callback) URLs. Wildcards are not supported.
4. Select Scopes
Select the required permissions (scopes) for your application. For scope details, see the Scope Configuration section.
5. In-House Use Configuration (Enterprise Tenants Only)
For Enterprise tenants, you can select whether to display an authorization screen (consent screen) to users. For trusted applications within your organization, skipping the authorization screen can improve user experience.
For SaaS tenants, the authorization screen is always displayed (cannot be changed). This is to obtain explicit user consent as a third-party application.
6. Complete Creation
Click the "Create" button to create the application. After creation, you will be redirected to the app detail screen. Here you can view Client ID and Client Secret (see the Confirm Authentication Information section for how to view them).
How to Choose Between Confidential and Public
Client Type cannot be changed after creation. Select based on your application's execution environment.
| Confidential | Public | |
|---|---|---|
| Execution Environment | Server-side (Node.js, Python, etc.) | Browser (SPA), Mobile applications |
| Client Secret | Present (required for token acquisition) | Not present (not issued) |
| PKCE | Optional (recommended) | Required (S256 only supported) |
| Web Origins | Auto-configured (no input needed) | Manual registration required |
Public clients have no Client Secret, so protection via PKCE (Proof Key for Code Exchange) is mandatory. Send code_challenge (S256 method) in the authorization request and send code_verifier in the token request. Methods other than S256 (like plain) are not supported.
CC Client (Client Credentials)
This is for system integration where end users are not involved, such as server-to-server communication and batch processing. Access tokens are obtained using only Client ID and Client Secret.
CC clients can only be created for Enterprise tenants. For SaaS tenants, authentication pattern selection is not displayed at all.
CC clients have the following characteristics:
- Always Confidential (has Client Secret)
- Publication status is fixed as Private (within Enterprise tenant only)
- Redirect URI is not required (no browser redirect)
- Refresh tokens are not issued (re-obtain after expiration)
- Service account (user ID for system) is automatically created
Steps to Create a CC Client
In Console for Enterprise tenants, create by going to "Applications" → "New Create" and selecting "Client Credentials" as the authentication pattern.
1. Enter Basic Information
In addition to the same basic information as AC clients, there are the following differences:
- Logo is optional (not required)
- Privacy Policy URL / Terms of Use URL are not required (no authorization screen)
- Publication status selection is not required (fixed as Private)
- Redirect URI / Web Origins are not required
2. Select Scopes
For CC clients, different scopes are available compared to AC. For details, see the Scope Configuration section.
3. Configure Service Account ID
When calling the API with a CC client, set the service account ID that determines "who" is performing the operation. For details, see the Service Account ID section.
4. Complete Creation
After creation, you can view Client ID and Client Secret on the app detail screen. Store Client Secret securely at the system integration destination.
Service Account ID
When calling the API with a CC client, AgenticStar internally processes it as a virtual user called "service account". There are two ways to set the ID for this service account.
| Link to Existing User | Service Account (Manual Configuration) | |
|---|---|---|
| Use Case | When calling API as a proxy for an existing user | When calling API with a system-dedicated independent ID |
| Configuration Method | Search and select user | Enter organization (optional), job type (optional), self-introduction (optional) |
| Change After Creation | Cannot be changed | Cannot be changed |
The service account ID method cannot be changed after creation. If you choose "Link to Existing User", you can access that user's conversation history and files, making it suitable for batch processing using specific user data. When using an independent ID, a system-dedicated conversation space is created.
Scope Configuration
Scopes define the authorization scope for APIs that a client can access. During client creation, select the required scopes from the scope list.
How Scopes Work
1. Assign Scopes to Client During client creation in Console, select the required scopes. The selected scopes become the "maximum range of permissions available for this client".
2. Filter by User Role (AC only) For AC clients, the scopes included in the token are the intersection (common part) of "scopes assigned to client" and "scopes permitted by logged-in user's role".
3. Scopes Included in Token When making API requests, scopes included in the access token are matched against the required scopes for each endpoint.
Available Scopes
The selectable scopes differ depending on the authentication pattern (AC / CC).
| Scope | AC | CC | Description |
|---|---|---|---|
openid | ✓ | ✓ | Required scope. Always included, cannot be deselected. |
[Chat] | |||
chat:all | — | ✓ | All chat functionality. Only available for CC clients. |
[Agent] | |||
agent:all | ✓ | ✓ | All agent functionality. |
[Admin] | |||
admin:all | ✓ | ✓ | All admin functionality. Only valid for users with admin role. |
[Develop] | |||
develop:all | ✓ | ✓ | Developer functionality. Only valid for users with developer role. |
Auto-Assigned Scopes for CC Clients
In addition to selected scopes, the following scopes are automatically assigned to CC clients. These are not displayed on the selection screen but are included in the token.
| Scope | Description |
|---|---|
cc:tenant | Include tenant information in token. Used to identify the tenant to which the service account belongs. |
cc:profile | Include service account profile information in token. |
Relationship Between Roles and Scopes (AC Clients)
For AC clients, the actual scopes included in the token vary depending on the role of the logged-in user. On the scope selection screen, required roles for each scope are displayed, so you can use the "Check" button to see which scopes each role can use.
| Role | Available Scopes |
|---|---|
| user | agent:all |
| admin | agent:all, admin:all |
| developer | agent:all, develop:all |
:::example Scope Filtering
If you assign agent:all and admin:all to a client, when a user with the user role logs in, only agent:all is included in the token. When a user with the admin role logs in, both agent:all and admin:all are included.
:::
For a complete list of scopes, see Authentication Guide.
Confirm Authentication Information
After client creation, the authentication information required for API usage can be confirmed on the app detail screen.
Client ID
Displayed in the "Technical Configuration" section on the app detail screen. Can be copied to clipboard using the copy button.
Client Secret
Confidential clients only (AC Confidential / CC). The app detail screen has the following action buttons.
| Action | Description |
|---|---|
| View | Click the eye icon to display the masked Client Secret. |
| Copy | Click the copy icon to copy Client Secret to clipboard. |
| Regenerate | Click the refresh icon to generate a new Client Secret. The previous secret is immediately invalidated. |
- Client Secret is confidential information equivalent to a password. Keep it secure.
- Do not hardcode in source code or version control systems. Environment variables or Secret Manager usage is recommended.
- Regenerating Client Secret will cause authentication to fail for all systems using the old secret. Check the scope of impact beforehand.
- Public clients (AC Public) are not issued Client Secret.
Next Steps
After obtaining authentication information, proceed to the following guides:
- Quickstart — Shortest route to experience API with curl
- Authentication Guide — Detailed steps for AC / CC flows
- API Reference — All endpoint specifications