OAuth Clients

OAuth client endpoints manage the applications that can use Aero2 as an identity provider. When you register a client, you get a client_id and client_secret that the application uses to authenticate with Aero2's token endpoint. Clients belong to the application determined by the subdomain.

GET/api/clientsAdmin

Returns all registered OAuth clients.

Response

{
  "clients": [
    {
      "id": "client-uuid",
      "client_id": "my-app",
      "name": "My Application",
      "redirect_uris": [
        "https://app.example.com/callback"
      ],
      "created_at": "2026-01-15T08:00:00Z"
    }
  ]
}

POST/api/clientsAdmin

Registers a new OAuth client. Returns the client secret (only shown once).

Parameter	Type	Description
name* body	string	Human-readable client name
redirect_uris* body	string[]	Allowed redirect URIs

Request

{
  "name": "My Application",
  "redirect_uris": [
    "https://app.example.com/callback"
  ]
}

Response

{
  "id": "client-uuid",
  "client_id": "generated-client-id",
  "client_secret": "generated-secret-shown-once",
  "name": "My Application",
  "redirect_uris": [
    "https://app.example.com/callback"
  ]
}

GET/api/clients/:idAdmin

Returns details of a specific OAuth client (secret is not included).

Parameter	Type	Description
id* path	string	Client ID

Response

{
  "id": "client-uuid",
  "client_id": "my-app",
  "name": "My Application",
  "redirect_uris": [
    "https://app.example.com/callback"
  ],
  "created_at": "2026-01-15T08:00:00Z"
}

PUT/api/clients/:idAdmin

Updates an OAuth client's configuration.

Parameter	Type	Description
id* path	string	Client ID
name body	string	Client name
redirect_uris body	string[]	Allowed redirect URIs

Request

{
  "name": "My Updated App",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://staging.example.com/callback"
  ]
}

Response

{
  "message": "Client updated"
}

DELETE/api/clients/:idAdmin

Deletes an OAuth client and revokes all associated grants.

Parameter	Type	Description
id* path	string	Client ID

Response

{
  "message": "Client deleted"
}

POST/api/clients/:id/rotate-secretAdmin

Generates a new client secret. The old secret is immediately invalidated. The new secret is only shown once.

Parameter	Type	Description
id* path	string	Client ID

Response

{
  "client_secret": "new-secret-shown-once"
}

GET/api/clients/:id/grantsAdmin

Returns all user grants (authorizations) for a specific client.

Parameter	Type	Description
id* path	string	Client ID

Response

{
  "grants": [
    {
      "id": "grant-uuid",
      "user_id": "user-uuid",
      "user_email": "jane@example.com",
      "scopes": "openid profile email",
      "created_at": "2026-02-01T10:00:00Z"
    }
  ]
}

DELETE/api/clients/:id/grantsAdmin

Revokes all user grants for a specific client. Users will need to re-authorize.

Parameter	Type	Description
id* path	string	Client ID

Response

{
  "message": "All grants revoked",
  "revoked_count": 5
}