AetherID

Identity, without noise

Developer Integration Guide

Integrate "Log in with AetherID" into your application. This guide details the OAuth 2.0 Authorization Code flow implementation for third-party developers.

Base URL: https://id.example.com

High-level Flow

AetherID implements the Authorization Code flow:

  1. App redirects user to AetherID login UI (GET /login).
  2. Login UI creates an authorization_code and redirects back.
  3. Backend exchanges code for token (POST /api/oauth/token).
  4. Backend requests user info (GET /api/oauth/userinfo).

1. Authorization

Authorization UI

GET /login?client_id=...&redirect_uri=...&response_type=code

Redirects to: {redirect_uri}?code={authorization_code}

2. Token Exchange

Endpoint

POST /api/oauth/token

Request Body (JSON)

{
  "grant_type": "authorization_code",
  "code": "<raw_authorization_code>",
  "redirectUri": "https://app-a.example.com/callback",
  "clientId": "<clientId>",
  "clientSecret": "<clientSecret>"
}

Success Response (200)

{
  "access_token": "<jwt_access_token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "<jwt_refresh_token>"
}

3. User Info

Endpoint

GET /api/oauth/userinfo

Header: Authorization: Bearer <access_token>

Response

{
  "sub": "<userId>",
  "email": "user@example.com",
  "name": "user_name",
  "preferred_username": "user_name",
  "email_verified": true
}

Client Registration

Go to Console

To get a clientId and clientSecret, you must register your application.

POST /api/client/register