OAuth Apps

OAuth Apps turn Project Authentication into an authorization server for services. A signed-in project user can approve explicit scopes for an app without giving that app the user's password or upstream social provider token.

#What an OAuth App is

#Register an app

In the project Authentication UI, add a name, client type, homepage, exact redirect URIs, and allowed scopes.

The client secret is shown once. Rotating it revokes existing OAuth tokens for that app.

#Authorization flow

GET https://api.agihalo.com/api/v1/auth/oauth/authorize
  ?client_id=halo_client_...
  &redirect_uri=https%3A%2F%2Fservice.example.com%2Fcallback
  &scope=profile%20email
  &state=opaque-client-state

The GET endpoint validates the client, redirect URI, and requested scopes, then returns app details for your consent UI. After the user approves, call the POST endpoint with the project user access token.

curl -X POST https://api.agihalo.com/api/v1/auth/oauth/authorize \
  -H "Authorization: Bearer $PROJECT_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "halo_client_...",
    "redirect_uri": "https://service.example.com/callback",
    "scopes": ["profile", "email"],
    "state": "opaque-client-state",
    "code_challenge": "S256_CHALLENGE",
    "code_challenge_method": "S256"
  }'

The response contains redirectTo. Navigate to that exact URL so the service receives code and the originalstate.

#Token exchange

curl -X POST https://api.agihalo.com/api/v1/auth/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "halo_client_...",
    "code": "halo_code_...",
    "redirect_uri": "https://service.example.com/callback",
    "code_verifier": "ORIGINAL_PKCE_VERIFIER"
  }'

Confidential clients also send client_secret. The authorization code is one-time and bound to the registered client, redirect URI, project user, scopes, and optional S256 challenge.

#User info & scopes

Send the OAuth access token as a bearer token. HALO validates its project, app, audience, token use, user status, and scopes before returning project-user information.