Authentication Reference

All authentication endpoints. For the conceptual guide, see Authentication.

Base path: /api/v1/auth/

GET /api/v1/auth/config#

Return OAuth configuration. No authentication.

Used by clients to discover the ScaiKey endpoints without hardcoding them.

Response:

1
2
3
4
5
6

{
  "authorize_url": "https://scaikey.scailabs.ai/oauth2/authorize",
  "token_url": "https://scaidrive.scailabs.ai/api/v1/auth/token",
  "client_id": "scaidrive-desktop",
  "desktop_callback_url": "https://scaidrive.scailabs.ai/api/v1/auth/callback"
}

GET /api/v1/auth/callback#

OAuth authorization-code relay for desktop clients. No authentication.

Purpose: desktop clients listen on http://localhost:<port>. ScaiKey redirects here with the code; ScaiDrive serves an HTML page that redirects to the localhost callback with the same query parameters.

Query parameters:

Response: HTML with JavaScript redirect to http://localhost:{port}/callback?code=...&state=....

POST /api/v1/auth/token#

Exchange an authorization code for tokens, or refresh. No authentication (the code is the authentication).

Request (form-encoded):

1
2
3
4

grant_type=authorization_code
code=<code>
redirect_uri=<original_redirect_uri>
code_verifier=<PKCE_verifier>

Or:

1
2

grant_type=refresh_token
refresh_token=<refresh_token>

Response:

1
2
3
4
5
6
7

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_...",
  "id_token": "eyJhbGc..."
}

Errors from ScaiKey (invalid code, expired refresh token, etc.) are surfaced in the standard error envelope with error.code as AUTH_TOKEN_INVALID.

Token scopes#

ScaiKey-issued tokens carry application scopes in the scope claim:

OIDC scopes (openid, profile, email, offline_access, address, phone) are recognized but don't affect ScaiDrive authorization.

Token claims used by ScaiDrive#

Validation errors#

Related#

• Authentication Guide
• Permissions and ACLs
• Error Codes