Exchange an API key for an access token
POST/api-keys/auth
Send the API key as the bearer token (Authorization: Bearer <api-key>) together with the userId of one of the key's linked users.
The response is an access token with that user's role, valid for the configured token lifetime (see expires).
If the key was created with scopes, the access token is restricted: every route that is not tagged
with one of the scopes returns 403 (Scope not allowed by token). The only useful scope is
system:register, which limits the token to POST /computers/register. system:ground_station is accepted
when creating a key, but no route in this product accepts it, so a token restricted to it cannot call anything.
Both application/json and application/x-www-form-urlencoded bodies are accepted.
Required role: none (authenticate with an API key).
Request
Responses
- 200
- 400
- 401
- 403
- 500
Access granted.
userId is missing, is not an object id, or is not one of the key's linked users (Invalid userId). A key created without linkedUsers always gets this response.
The token is not an API key (This token type is not allowed.), or it is expired, malformed or has a bad signature (jwt expired, jwt malformed, invalid signature). Also returned, as the typed shape, when the linked user exists but has no role (Access has not been granted for this user.).
The key is revoked or unknown (This token is not a valid API key) or the linked user no longer
exists (Requested user not found).
The access token could not be issued (No cached linked user). If no
token is sent at all, the server returns 500 with the generic {error} body. Send the API key in the Authorization: Bearer header.