OAuth

AIUS provides a full OAuth 2.0 and OpenID Connect (OIDC) provider that allows third-party applications to authenticate users using AIUS accounts.

Overview

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on an HTTP service. OpenID Connect (OIDC) is an authentication layer built on top of OAuth 2.0 that allows clients to verify the identity of the user and obtain basic profile information.

Features

OAuth 2.0 Authorization Code Flow with PKCE (S256) for public clients
OAuth 2.0 Authorization Code Flow for confidential clients
OpenID Connect (OIDC) with ID tokens
JWT Access Tokens signed with RS256
Token Introspection and Revocation endpoints
Refresh Token Rotation for enhanced security
Scope-based Authorization

How It Works

Redirect users to AIUS for authentication
Receive an authorization code after user consent
Exchange the code for access tokens
Use tokens to access AIUS APIs on behalf of the user

Authorization Flow

The OAuth 2.0 authorization code flow is the most secure OAuth flow, suitable for both public and confidential clients.

Step 1: Redirect to Authorization Endpoint

GET https://aius.co/api/oauth/authorize

Parameters:

Parameter	Required	Description
`response_type`	Yes	Must be `code`
`client_id`	Yes	Your OAuth client ID
`redirect_uri`	Yes	Must match registered URI (HTTPS, except localhost)
`scope`	Yes	Requested scopes (space-separated)
`state`	Yes	Random string for CSRF protection
`code_challenge`	Yes*	PKCE challenge (required for public clients)
`code_challenge_method`	Yes*	Must be `S256` (required for public clients)
`nonce`	Yes*	Random string for replay protection (required for OIDC)

*Required for public clients or OIDC flows Example:

GET https://aius.co/api/oauth/authorize?
  response_type=code&
  client_id=cli_f12391458360404d99ce9815&
  redirect_uri=https://your-app.com/callback&
  scope=openid%20profile%20email&
  state=abc123xyz&
  code_challenge=dGVzdF9jaGFsbGVuZ2U&
  code_challenge_method=S256&
  nonce=xyz789abc

The user signs in to their AIUS account and reviews the permissions your application is requesting. If they grant consent, AIUS redirects back to your app with an authorization code.

Step 3: Receive Authorization Code

https://your-app.com/callback?
  code=AUTHORIZATION_CODE&
  state=abc123xyz

Always verify the state parameter matches the one you sent to prevent CSRF attacks.

PKCE Implementation (Public Clients)

For public clients (mobile apps, SPAs), you must implement PKCE:

import secrets
import base64
import hashlib

# Generate code verifier
code_verifier = secrets.token_urlsafe(32)

# Generate code challenge
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode()).digest()
).rstrip(b'=').decode()

import crypto from 'crypto';

const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

Token Exchange

After receiving an authorization code, exchange it for access and refresh tokens.

Token Endpoint

POST https://aius.co/api/oauth/token
Content-Type: application/x-www-form-urlencoded

Authorization Code Grant

POST https://aius.co/api/oauth/token

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://your-app.com/callback&
client_id=cli_f12391458360404d99ce9815&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=YOUR_CODE_VERIFIER

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abc123...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

Refresh Token Grant

POST https://aius.co/api/oauth/token

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=cli_f12391458360404d99ce9815&
client_secret=YOUR_CLIENT_SECRET

Important: AIUS implements refresh token rotation. Each time you use a refresh token, you receive a new one and the old one is immediately revoked.

Using Access Tokens

Include the access token in the Authorization header:

GET https://aius.co/api/v1/organizations
Authorization: Bearer YOUR_ACCESS_TOKEN

Access tokens expire after 1 hour. Implement token refresh before expiration.

Scopes

Scopes define the permissions your application can request.

Available Scopes

Identity Scopes:

openid - Required for OpenID Connect
profile - Basic user profile information (name, picture)
email - User email and verification status

API Scopes:

orgs:read - Read access to organizations
orgs:write - Write access to organizations
api:read - Read access to AIUS API
api:write - Write access to AIUS API

Requesting Scopes

Include scopes as a space-separated list:

scope=openid profile email api:read

Request only the scopes your application needs. Users see the exact scopes you request on the consent screen.

Client Management

Client Types

Public Clients (cannot securely store secrets):

Mobile apps
Single-page applications (SPAs)
Native desktop applications

Confidential Clients (can securely store secrets):

Web servers
Backend services

Registering a Client

Contact AIUS support to register your OAuth client. You’ll need to provide:

Application name and description
Redirect URIs (must be HTTPS, except localhost)
Required scopes
Client type (public or confidential)

Redirect URI Requirements

Must use HTTPS in production (localhost is exception)
Must match exactly (including path and query parameters)
No wildcard support - register each exact URI

Security Best Practices

Store secrets in environment variables or secure secret management systems
Never hardcode secrets in source code
Always use HTTPS for redirect URIs in production
Request only the scopes your application needs
Rotate client secrets regularly

Security Features

PKCE mandatory for public clients (S256)
State parameter mandatory for all flows (CSRF protection)
Redirect URI validation with exact match allow-list
Client authentication for confidential clients
Short-lived access tokens (1 hour)
Refresh token rotation on every use
Token revocation support

Getting Started

Register an OAuth Client - Contact AIUS support
Implement Authorization Flow - Redirect users to AIUS authorization endpoint
Exchange Tokens - Use the token exchange endpoint
Access Protected Resources - Use access tokens to access AIUS APIs

Support

For OAuth client registration, configuration, or management issues:

Email: support@aius.co
Include your client_id in all communications

​OAuth

​Overview

​Features

​How It Works

​Authorization Flow

​Step 1: Redirect to Authorization Endpoint

​Step 2: User Authentication and Consent

​Step 3: Receive Authorization Code

​PKCE Implementation (Public Clients)

​Token Exchange

​Token Endpoint

​Authorization Code Grant

​Refresh Token Grant

​Using Access Tokens

​Scopes

​Available Scopes

​Requesting Scopes

​Client Management

​Client Types

​Registering a Client

​Redirect URI Requirements

​Security Best Practices

​Security Features

​Getting Started

​Support