Overview
The Aya API uses JWT (JSON Web Tokens) for authentication. Tokens are obtained via OAuth2 flows with supported providers.
Supported OAuth Providers
GitHub
Authenticate with GitHub
Bluesky
Authenticate with Bluesky
Authentication Flow
1. Initiate OAuth Login
Redirect users to the OAuth login endpoint:
GET /{locale}/auth/{authProvider}/login?redirect_uri=YOUR_REDIRECT_URI
Locale code (e.g., en, fr, ja)
OAuth provider: github, apple, bsky, x, youtube, linkedin
URL to redirect to after authentication
GET http://localhost:8080/en/auth/github/login?redirect_uri=https://your-app.com/callback
2. Handle OAuth Callback
After authentication, the provider redirects back with a code:
GET /{locale}/auth/{authProvider}/callback?code=CODE&state=STATE&redirect_uri=REDIRECT_URI
- Exchange the code for an access token
- Create or update the user account
- Generate a JWT token
- Set a session cookie (for same-domain requests)
- Redirect to your
redirect_uri
Response:
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"email": "[email protected]",
"name": "John Doe",
"kind": "standard",
"individual_profile_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
"profile_picture_uri": "https://avatars.githubusercontent.com/u/12345"
}
},
"error": null
}
JWT token for API authentication
3. Use the JWT Token
Include the JWT token in the Authorization header:
Authorization: Bearer YOUR_JWT_TOKEN
curl -X GET http://localhost:8080/en/users/me \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Refresh Token
JWT tokens expire after 365 days. Refresh them before expiration:
POST /{locale}/auth/refresh
Authorization: Bearer YOUR_JWT_TOKEN
curl -X POST http://localhost:8080/en/auth/refresh \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresAt": 1735689600
},
"error": null
}
Logout
Invalidate the current session:
POST /{locale}/auth/logout
curl -X POST http://localhost:8080/en/auth/logout \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Session Cookie (Cross-Domain SSO)
For same-domain requests, the API sets a session cookie:
- Name:
aya_session
- Domain:
.aya.is
- Secure:
true (HTTPS only)
- SameSite:
Lax
This enables cross-domain SSO across Aya subdomains without requiring explicit Bearer tokens.
JWT Token Structure
Tokens contain the following claims:
{
"session_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"exp": 1735689600
}
Never expose JWT tokens in client-side code or logs. Store them securely and transmit only over HTTPS.
Error Responses
{
"data": null,
"error": {
"message": "Unauthorized",
"code": 401
}
}
Security Best Practices
- Store tokens securely (e.g., httpOnly cookies, encrypted storage)
- Always use HTTPS in production
- Implement token refresh before expiration
- Rotate secrets regularly
- Monitor for suspicious authentication patterns
