Skip to main content

API Endpoints

Complete reference for all S-Auth OAuth Provider API endpoints.

Base URL​

https://auth.sebbyk.net

OAuth2 Endpoints​

GET /authorize​

Start the authorization flow. Redirects user to login if not authenticated.

Parameters (Query String)

ParameterRequiredDescription
response_typeYesMust be code
client_idYesYour application's client ID
redirect_uriYesMust match registered URI
scopeNoSpace-separated scopes
stateRecommendedCSRF protection value
code_challengePKCEBASE64URL(SHA256(verifier))
code_challenge_methodPKCES256 or plain

Success Response

Redirects to redirect_uri with:

?code=AUTH_CODE&state=STATE

Error Response

Redirects to redirect_uri with:

?error=ERROR_CODE&error_description=DESCRIPTION&state=STATE

POST /token​

Exchange authorization code or credentials for tokens.

Headers

Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)  # For confidential clients

Authorization Code Grant​

Request Body

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=REDIRECT_URI
&code_verifier=VERIFIER  # For PKCE
&client_id=CLIENT_ID     # For public clients

Response

{
  "access_token": "sat_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "srt_...",
  "scope": "openid profile email"
}

Client Credentials Grant​

Request Body

grant_type=client_credentials
&scope=SCOPES

Response

{
  "access_token": "sat_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "requested_scope"
}

Refresh Token Grant​

Request Body

grant_type=refresh_token
&refresh_token=srt_...

Response

{
  "access_token": "sat_...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "srt_...",
  "scope": "openid profile email"
}

GET /userinfo​

Get information about the authenticated user.

Headers

Authorization: Bearer ACCESS_TOKEN

Response

{
  "sub": "user-uuid",
  "user_id": "JD-1234",
  "email": "john@example.com",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe"
}

POST /revoke​

Revoke an access token or refresh token.

Headers

Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

Request Body

token=TOKEN_TO_REVOKE
&token_type_hint=access_token  # or refresh_token

Response

HTTP 200 OK

Always returns 200, even if token was already revoked or invalid.

GET /.well-known/openid-configuration​

OpenID Connect discovery document.

Response

{
  "issuer": "https://auth.sebbyk.net",
  "authorization_endpoint": "https://auth.sebbyk.net/authorize",
  "token_endpoint": "https://auth.sebbyk.net/token",
  "userinfo_endpoint": "https://auth.sebbyk.net/userinfo",
  "revocation_endpoint": "https://auth.sebbyk.net/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials", "refresh_token"],
  "code_challenge_methods_supported": ["S256", "plain"],
  "scopes_supported": ["openid", "profile", "email"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

Admin API Endpoints​

All admin endpoints require Bearer token authentication with admin access level.

Headers

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Users​

GET /admin/users​

List all users.

Query Parameters

ParameterDescription
pagePage number (default: 1)
limitItems per page (default: 20)
searchSearch by name or email

Response

{
  "users": [
    {
      "id": "uuid",
      "user_id": "JD-1234",
      "email": "john@example.com",
      "fname": "John",
      "lname": "Doe",
      "access_level": "user",
      "created_at": 1234567890,
      "last_login_at": 1234567890
    }
  ],
  "total": 50,
  "page": 1,
  "limit": 20
}

POST /admin/users​

Create a new user.

Request Body

{
  "email": "jane@example.com",
  "fname": "Jane",
  "lname": "Doe",
  "password": "SecurePass123!",
  "access_level": "user"
}

Response

{
  "id": "uuid",
  "user_id": "JD-5678",
  "email": "jane@example.com",
  "fname": "Jane",
  "lname": "Doe",
  "access_level": "user",
  "created_at": 1234567890
}

GET /admin/users/:id​

Get a specific user.

Response

{
  "id": "uuid",
  "user_id": "JD-1234",
  "email": "john@example.com",
  "fname": "John",
  "lname": "Doe",
  "access_level": "user",
  "created_at": 1234567890,
  "updated_at": 1234567890,
  "last_login_at": 1234567890
}

PUT /admin/users/:id​

Update a user.

Request Body

{
  "email": "newemail@example.com",
  "fname": "John",
  "lname": "Smith",
  "access_level": "admin"
}

Response

{
  "id": "uuid",
  "user_id": "JD-1234",
  "email": "newemail@example.com",
  "fname": "John",
  "lname": "Smith",
  "access_level": "admin",
  "updated_at": 1234567890
}

DELETE /admin/users/:id​

Delete a user.

Response

{
  "success": true
}

POST /admin/users/:id/reset-password​

Reset a user's password.

Response

{
  "temporary_password": "xK9#mP2$vL5@nQ8"
}

OAuth Clients​

GET /admin/clients​

List all OAuth clients.

Response

{
  "clients": [
    {
      "id": "uuid",
      "client_id": "my-app",
      "name": "My Application",
      "description": "A useful application",
      "redirect_uris": ["https://myapp.com/callback"],
      "allowed_grants": ["authorization_code", "refresh_token"],
      "allowed_scopes": ["openid", "profile", "email"],
      "is_confidential": true,
      "logo_emoji": "📊",
      "is_public": true,
      "created_at": 1234567890
    }
  ]
}

POST /admin/clients​

Create a new OAuth client.

Request Body

{
  "name": "My New App",
  "description": "Description here",
  "redirect_uris": ["https://myapp.com/callback"],
  "allowed_grants": ["authorization_code", "refresh_token"],
  "allowed_scopes": ["openid", "profile", "email"],
  "is_confidential": true,
  "logo_emoji": "🚀",
  "is_public": false
}

Response

{
  "id": "uuid",
  "client_id": "generated-client-id",
  "client_secret": "scs_...",
  "name": "My New App",
  ...
}

GET /admin/clients/:id​

Get a specific client.

PUT /admin/clients/:id​

Update a client.

DELETE /admin/clients/:id​

Delete a client.

User API Endpoints​

GET /api/user/applications​

Get applications available to the authenticated user.

Headers

Authorization: Bearer ACCESS_TOKEN

Response

[
  {
    "client_id": "my-app",
    "name": "My Application",
    "description": "A useful app",
    "logo_emoji": "📊",
    "is_public": true,
    "is_authorized": true,
    "redirect_uri": "https://myapp.com/callback"
  }
]

Health & Monitoring​

GET /health​

Simple health check.

Response

{
  "status": "ok"
}

GET /health/detailed​

Detailed health check with dependency status.

Response

{
  "status": "healthy",
  "service": "s-auth-oauth-provider",
  "timestamp": "2024-01-15T12:00:00Z",
  "total_latency_ms": 15,
  "checks": {
    "database": {
      "status": "ok",
      "latency_ms": 12
    }
  }
}

GET /metrics​

Prometheus-format metrics.

Response

# HELP sauth_users_total Total number of users
# TYPE sauth_users_total gauge
sauth_users_total 42

# HELP sauth_clients_total Total number of OAuth clients
# TYPE sauth_clients_total gauge
sauth_clients_total 5

# HELP sauth_active_sessions Active sessions count
# TYPE sauth_active_sessions gauge
sauth_active_sessions 15

# HELP sauth_active_tokens Active access tokens count
# TYPE sauth_active_tokens gauge
sauth_active_tokens 28