OAuth clients - Rookoo API

Rookoo issues OAuth 2.0 access tokens as JWTs (RS256). Account administrators can register OAuth clients under Settings → Integrations → OAuth Applications. Super admins can also manage global clients (no account) in the super admin console. Account-scoped clients are tied to the account that created them. Only administrators of that account can list, update, or delete them.

Scopes

Scope	Default	Description
`profile`	Yes	Basic user identity (id, email, name)
`accounts`	No	Account IDs the user belongs to
`read`	No	Read access to Application API resources
`write`	No	Write access to Application API resources

Create a client in the portal

Open Settings → Integrations → OAuth Applications.
Click New OAuth App.
Set a name, redirect URI, and scopes.
Copy the Client ID (uid) and Client Secret. The secret is shown in the app details and can be regenerated later.

Redirect URIs must use https, a custom scheme (for native apps), or http on localhost / 127.0.0.1. Public (non-confidential) clients must use PKCE.

Create a client via API

Requires an administrator user access token:

curl -X POST https://app.rookoo.ai/api/v1/accounts/1/oauth_applications \
  -H "api_access_token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oauth_application": {
      "name": "My Integration",
      "redirect_uri": "https://myapp.com/oauth/callback",
      "scopes": "profile read write",
      "confidential": true
    }
  }'

Response includes uid (client id) and secret. Regenerate the secret:

curl -X POST https://app.rookoo.ai/api/v1/accounts/1/oauth_applications/1/regenerate_secret \
  -H "api_access_token: YOUR_ACCESS_TOKEN"

Authorization code flow

1. Send the user to authorize

https://app.rookoo.ai/oauth/authorize?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fmyapp.com%2Foauth%2Fcallback&response_type=code&scope=profile+read&code_challenge=CHALLENGE&code_challenge_method=S256

The user must be signed in to the portal. After approval they are redirected with ?code=....

2. Exchange the code for tokens

curl -X POST https://app.rookoo.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "redirect_uri=https://myapp.com/oauth/callback" \
  -d "code_verifier=VERIFIER"

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "...",
  "scope": "profile read",
  "created_at": 1710000000
}

Access tokens expire after 2 hours. Use the refresh token to obtain a new access token without re-prompting the user.

3. Call the API

curl https://app.rookoo.ai/api/v1/accounts/1/conversations \
  -H "Authorization: Bearer ACCESS_TOKEN"

OAuth JWTs use the Authorization: Bearer header (not api_access_token). The token user must be a member of the account in the path.

Client credentials flow

For machine-to-machine clients that do not act as a user. Prefer authorization code when the integration needs user permissions.

curl -X POST https://app.rookoo.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "scope=profile+read"

Refresh tokens

curl -X POST https://app.rookoo.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET"

Discovery endpoints

URL	Purpose
`/.well-known/oauth-authorization-server`	Authorization server metadata
`/.well-known/oauth-protected-resource`	Protected resource metadata (MCP and API)
`/.well-known/jwks.json`	JWT verification keys
`POST /oauth/register`	Dynamic client registration

Manage clients via API

Method	Path	Description
`GET`	`/api/v1/accounts/{account_id}/oauth_applications`	List clients
`POST`	`/api/v1/accounts/{account_id}/oauth_applications`	Create client
`GET`	`/api/v1/accounts/{account_id}/oauth_applications/{id}`	Show client
`PATCH`	`/api/v1/accounts/{account_id}/oauth_applications/{id}`	Update redirect URI / scopes
`DELETE`	`/api/v1/accounts/{account_id}/oauth_applications/{id}`	Delete client
`POST`	`/api/v1/accounts/{account_id}/oauth_applications/{id}/regenerate_secret`	Rotate secret

All of these routes require an administrator of {account_id}.

​Scopes

​Create a client in the portal

​Create a client via API

​Authorization code flow

​1. Send the user to authorize

​2. Exchange the code for tokens

​3. Call the API

​Client credentials flow

​Refresh tokens

​Discovery endpoints

​Manage clients via API