Authentication

All endpoints except /auth/login require a Bearer token. REST clients and non-browser WebSocket clients normally send it in the Authorization header; browser WebSocket clients use the approved query-token form described below.

---

Login

Cloud

To access the Cloud API, you first need an API token from your Cogniteam Cloud Platform organization. See the Creating a Token guide for how to generate one.

Endpoint

POST /auth/login

Request Body

{
  "userToken": "your_api_token_here"
}

Response

{
  "token": "bearer your_bearer_token_here"
}

Local

Local API Gateway uses a short-lived bearer token issued by the local agent. The login request uses the local agent token or password, not a cloud user profile token.

If the Agent has NoAuthentication enabled, protected Local routes bypass bearer validation entirely. Login still works with any submitted value, but clients do not need to call it or send a token.

Endpoint

POST /auth/login

Request Body

{
  "userToken": "local-agent-token-or-password"
}

Response

{
  "token": "bearer local-api-gateway-token"
}

---

Using the Token

Include the token in the Authorization header of every subsequent request:

{
  "authorization": "bearer <token>"
}

---

Token Notes

Cloud

The Bearer token may expire. Re-authenticate if you receive a 401 Unauthorized response.

Local

• Tokens are stored in memory by the agent.
• Tokens expire after 12 hours.
• Tokens do not survive an agent restart.
• With NoAuthentication enabled, protected Local REST and WebSocket routes do not require a bearer token. Login remains available but is optional.

---

Browser WebSocket Authentication

Local only

Browser WebSocket clients cannot set custom Authorization headers. For Local API Gateway WebSocket routes, send the token as an access_token query parameter instead:

ws://<agent-host>:19992/apigateway/v2/robots/{robotId}/streams/connect?access_token=<token>

ws://<agent-host>:19992/apigateway/v2/fleets/local-fleet/custom-kpis?access_token=<token>

You may pass either the raw token or the value with the bearer prefix. Query-token authentication is accepted only on approved WebSocket upgrade routes.

---

Common Errors

Cloud

401: token is missing or expired — re-authenticate.

Local

• 400: request body is missing.
• 401: the local password is invalid during login, or a required bearer token is missing, expired, or invalid. Login again after an Agent restart.
• 403: Local API Gateway is disabled.