API Reference

All API endpoints are under https://id.fabi-sc.com/api/v1/.

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Most endpoints also require a user token in the X-User-Token header:

X-User-Token: USER_TOKEN

Response Format

All responses follow this format:

{
  "success": true|false,
  "data": { ... } | null,
  "error": "Error message" | null,
  "reconsent": true|false
}

The reconsent flag indicates whether the user needs to reconnect your application. If true, redirect the user to the login page.

POST /exchange

Exchange a one-time code for an access token.

Headers:

• Authorization: Bearer API_KEY (required)

Request Body:

{
  "code": "authorization-code"
}

Response:

{
  "success": true,
  "data": {
    "token": "user-access-token",
    "user_id": "derived-user-uuid",
    "scopes": ["openid", "username", "email"]
  },
  "reconsent": false
}

Notes:

• The code is single-use and expires after 5 minutes
• The token lifetime is configured in your application settings
• The user_id is a derived ID unique to your application

Errors:

POST /validate

Check if a user token is still valid.

Headers:

• Authorization: Bearer API_KEY (required)

Request Body:

{
  "token": "user-access-token"
}

Response (valid token):

{
  "success": true,
  "data": {
    "valid": true,
    "user_id": "derived-user-uuid"
  },
  "reconsent": false
}

Response (invalid/expired token):

{
  "success": true,
  "data": {
    "valid": false,
    "user_id": null
  },
  "reconsent": false
}

Response (re-consent needed):

{
  "success": false,
  "error": "Re-consent required",
  "reconsent": true
}

Notes:

• success indicates whether the API request itself succeeded (valid API key, no server errors)
• valid indicates whether the token is valid
• A request can have success: true with valid: false (e.g., expired token)
• Banned users return valid: false
• If reconsent is true, redirect the user to reconnect

Errors:

GET /user

Get user data for the authenticated user.

Headers:

• Authorization: Bearer API_KEY (required)
• X-User-Token: USER_TOKEN (required)

Response:

{
  "success": true,
  "data": {
    "id": "derived-user-uuid",
    "username": "johndoe",
    "display_name": "John Doe",
    "avatar_url": "https://...",
    "locale": "en",
    "email": "john@example.com",
    "email_verified": true,
    "date_of_birth": "1990-01-15",
    "first_name": "John",
    "last_name": "Doe",
    "bio": "Software developer",
    "website_links": ["https://johndoe.com"],
    "timezone": "Europe/Berlin"
  },
  "reconsent": false
}

Notes:

• Only fields for granted scopes are returned
• Fields the user hasn’t filled in are null
• The id field is always present (scope openid)

Errors:

GET /avatar

Download the authenticated user’s avatar image.

Headers:

• Authorization: Bearer API_KEY (required)
• X-User-Token: USER_TOKEN (required)

Query Parameters:

• format: Image format - webp or jpg (required)

Response:

• Content-Type: image/webp or image/jpeg
• Cache-Control: private, max-age=3600

Returns the binary image data.

Errors:

POST /revoke

Revoke a user token. Use this when a user logs out of your application.

Headers:

• Authorization: Bearer API_KEY (required)

Request Body:

{
  "token": "user-access-token"
}

Response:

{
  "success": true,
  "data": {
    "revoked": true
  },
  "reconsent": false
}

POST /force-reconsent

Force a user to reconnect your application. Use this when you’ve added new optional scopes and want the user to see them.

Headers:

• Authorization: Bearer API_KEY (required)
• X-User-Token: USER_TOKEN (required)

Response:

{
  "success": true,
  "data": {
    "triggered": true
  },
  "reconsent": false
}

Notes:

• The next time you validate the user’s token, reconsent will be true
• The user will see the updated scopes when they reconnect

Errors:

Common Error Responses