Authentication Reference

All authentication and session endpoints. For the conceptual overview, see Authentication.

Base path: /v3/auth/

Most endpoints in this section require no credentials themselves (they produce credentials); /v3/auth/me is the exception.

POST /v3/auth/login#

Initiate an OAuth login flow with ScaiKey. Returns the authorization URL the browser should redirect to.

Request:

1

{"email": "you@example.com"}

Response (200):

1
2
3
4

{
  "authorization_url": "https://scaikey.scailabs.ai/oauth/authorize?...",
  "state": "opaque-state-string"
}

The state must be passed back to /v3/auth/callback. Store it (session, cookie) for CSRF verification.

POST /v3/auth/callback#

Exchange an OAuth authorization code for tokens.

Request:

1

{"code": "authorization-code-from-oauth-redirect", "state": "opaque-state-string"}

Response (200):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "access_token": "eyJhbGc...",
  "refresh_token": "rtk_...",
  "expires_in": 3600,
  "user": {
    "id": "usr_01HXYZ",
    "email": "you@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "display_name": "Ada Lovelace",
    "tenant_id": "tnt_acme"
  }
}

Errors: 400 if code is invalid or expired, 401 if state mismatch.

POST /v3/auth/refresh#

Exchange a refresh token for a fresh access token.

Request:

1

{"refresh_token": "rtk_..."}

Response (200):

1
2
3
4
5

{
  "access_token": "eyJhbGc...",
  "refresh_token": "rtk_...",
  "expires_in": 3600
}

A new refresh token may be returned (rotation). If so, replace the old one.

Errors: 401 if refresh token is invalid, expired, or revoked.

POST /v3/auth/logout#

Logout is stateless — the server has no session to destroy. The client is expected to discard its tokens.

Response (200):

1

{"status": "ok"}

GET /v3/auth/me#

Return the current user's profile and effective permissions. Requires a valid JWT.

Response (200):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "data": {
    "id": "usr_01HXYZ",
    "email": "you@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "display_name": "Ada Lovelace",
    "name": "Ada Lovelace",
    "status": "active",
    "tenant_id": "tnt_acme",
    "permissions": ["mail.send", "templates.read", "stats.read"],
    "role": "developer"
  }
}

permissions is the union of permissions granted by every role the user holds (direct role assignments + group-mapped roles + nested group inheritance). Use this to render UI affordances conditionally.

Errors: 401 if no JWT or JWT invalid.

Authorization header format#

Every authenticated request uses:

1

Authorization: Bearer <credential>

Where <credential> is either an API key (sg_live_* / sg_test_*) or a ScaiKey-issued JWT. ScaiSend determines which by the prefix.

Related#

• Authentication (guide)
• API Keys Reference
• Roles and Permissions