Authentication

Every REST endpoint is under /api/v1 and is scoped to your organization. There are two ways to authenticate, one for people and one for services.

Base URL

Environment	Base URL
Hosted	https://api.agenticsuite.app
Local	http://localhost:8002

Examples below use the local URL. Swap in the hosted URL in production.

Option 1: Bearer token (for people)

Log in with email and password to get a JSON Web Token, then send it as a bearer token on every request. Tokens are short-lived; use the refresh token to rotate them.

POST /api/v1/iam/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

The response includes an access_token and a refresh_token:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "..."
}

Send the access token on every subsequent call:

GET /api/v1/agents
Authorization: Bearer eyJhbGciOi...

When the access token expires, exchange the refresh token for a new one:

POST /api/v1/iam/auth/refresh
Content-Type: application/json

{ "refresh_token": "..." }

Bearer tokens carry the full permissions of the user who logged in. Use them for interactive tools and short-lived sessions.

Option 2: API key (for services)

For server-to-server integrations, create an API key and send it in the X-API-Key header. API keys do not expire on a session clock, can be scoped, and can be revoked without changing a password.

Create a key (authenticated as a user with permission to do so):

POST /api/v1/iam/api-keys
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "name": "Production integration",
  "environment": "live"
}

The response returns the secret once. Store it securely; it is not shown again.

{
  "data": {
    "id": "…",
    "key_prefix": "sk_live_…",
    "api_key": "sk_live_…the-full-secret…",
    "environment": "live"
  }
}

Then authenticate every call with the header:

GET /api/v1/agents
X-API-Key: sk_live_…the-full-secret…

Rotate keys by creating a new one and deleting the old one. The key_prefix is safe to log; the full api_key is not.

Which one to use

• Building a product or automation that runs unattended? Use an API key.
• Building an interactive tool a person signs into? Use a bearer token.

Errors

• 401 Unauthorized: missing, invalid, or expired credentials.
• 402 Payment Required: no active subscription, or the usage quota is spent.
• 403 Forbidden: authenticated, but not permitted for this action or resource.

Next: Agents.