Authentication

The Smart Agents API uses JWT bearer tokens for authentication. Tokens are obtained by exchanging your API key or by using the OAuth 2.0 client credentials flow.

API Keys

API keys are the simplest way to authenticate. You can generate API keys in the Smart Agents Portal under Settings > API Keys.

API keys have the format:

sa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Test environment keys use the prefix sa_test_.

Using an API Key Directly

You can use an API key directly as a bearer token for quick integrations:

curl -X GET https://api.agent.net.ai/v1/agents \
  -H "Authorization: Bearer sa_live_xxxxxxxxxxxxxxxxxxxx"

Generating a JWT Token from an API Key

For longer sessions, exchange your API key for a short-lived JWT token:

curl -X POST https://api.agent.net.ai/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "sa_live_xxxxxxxxxxxxxxxxxxxx"
  }'

Response:

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-04-12T11:30:00Z"
  }
}

Use the returned access_token for subsequent requests:

curl -X GET https://api.agent.net.ai/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

OAuth 2.0 Client Credentials

For server-to-server integrations, use the OAuth 2.0 client credentials flow.

Registering an OAuth Client

Navigate to the Smart Agents Portal > Settings > OAuth Applications
Click New Application
Enter an application name and description
Record the client_id and client_secret

Requesting a Token

curl -X POST https://api.agent.net.ai/v1/auth/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "scope=agents:read agents:write credits:read"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "agents:read agents:write credits:read"
}

Token Scopes

Tokens can be scoped to limit their capabilities:

Scope	Description
`agents:read`	List and view agents
`agents:write`	Create, update, and delete agents
`agents:chat`	Send messages to agents
`templates:read`	List and view templates
`templates:write`	Activate and deactivate templates
`credits:read`	View credit balance and usage
`credits:write`	Allocate credits to users
`users:read`	List and view user accounts
`users:write`	Manage user registrations and roles
`webhooks:read`	List and view webhooks
`webhooks:write`	Create, update, and delete webhooks
`audit:read`	View audit log entries

When no scope is specified, the token receives all scopes available to the API key.

JWT tokens expire after the period specified in expires_in (default: 1 hour). To refresh a token, request a new one using your API key or OAuth credentials. There is no refresh token flow; simply obtain a new access token before the current one expires.

Revoking API Keys

To revoke an API key:

curl -X DELETE https://api.agent.net.ai/v1/auth/keys/key_id \
  -H "Authorization: Bearer <admin-token>"

Revoking an API key immediately invalidates all tokens generated from that key.

Security Best Practices

Store API keys in environment variables or a secret manager (e.g., Azure Key Vault), not in source code
Use the narrowest scopes possible for each integration
Rotate API keys periodically (recommended: every 90 days)
Use test keys (sa_test_) during development
Monitor the audit log for unusual API activity
Revoke keys immediately if they are compromised