Create OAuth Client | Rightbrain Docs — Build reliable AI agents

curl -X POST https://app.rightbrain.ai/api/v1/org/org_id/project/project_id/oauth_client \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Customer Portal",
  "description": "Sign-in for the customer portal.",
  "redirect_uris": [
    "https://app.example.com/callback",
    "https://app.example.com/silent-refresh"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ]
}'

{
  "id": "019f8a01-2b21-7001-9c2b-3b6d0e5f1011",
  "name": "Support Portal",
  "client_id": "019f8a01-2b21-7002-9c2b-3b6d0e5f1012",
  "project_id": "019f8a00-1a10-7002-8b1a-2a5c9d4e0002",
  "created": "2026-02-03T08:05:00Z",
  "modified": "2026-02-03T08:05:00Z",
  "description": "Web app backend for the customer support portal",
  "redirect_uris": [
    "https://support.example.com/oauth/callback"
  ],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "client_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
  "token_endpoint_auth_method": "client_secret_basic",
  "pkce_required": false,
  "pkce_challenge_method": null,
  "deleted": null
}

Create a new OAuth client for API access.

OAuth clients enable:

Third-party application integration
Service-to-service authentication
Mobile app authentication
CLI tool access

Choosing the Right Grant Type:

Use Case	Grant Type	PKCE	Notes
Web app with backend	`authorization_code`	Optional	Most secure for user-facing apps
Mobile/Desktop app	`authorization_code`	Required	Public client, no secret storage
Server-to-server	`client_credentials`	No	For automated services, no user context
Single-page app	`authorization_code`	Required	Use PKCE instead of implicit
Long-lived sessions	Add `refresh_token`	-	Combine with primary grant type

Grant Type Details:

authorization_code: User authorizes app via browser, app exchanges code for tokens
client_credentials: Service authenticates directly with client_id/secret (no user)
refresh_token: Exchange refresh token for new access token (add to other grants)
implicit: Deprecated - Use authorization_code + PKCE instead

PKCE Support:

Enable PKCE for public clients (mobile apps, SPAs)
Supports S256 (SHA-256) and plain challenge methods
Required for clients without client secrets

type — user client or service account:

type accepts exactly "user" (the default) or "project", and decides whose permissions the client carries. Any other value is rejected with 422.

"user": the client acts as the user who created it and inherits that user’s permissions. Only that user is made an owner of the client.
"project": a service account is created for the client, so it carries project-level permissions rather than one person’s, and every member of the project is granted viewer access to the client. Use this for automation that must keep working after the creating user leaves.

type is not echoed back: it appears on no response field, so read it back from behaviour rather than from the created object.

Fields silently ignored: the request model is UserOAuthClientCreate. Any key it does not declare is dropped rather than rejected — notably scopes, profile and access_token_type, which appeared in older references. Scopes are fixed at offline_access and the access token type at opaque; sending different values changes nothing and the create still returns 200.

client_secret is returned only once, in this response — store it securely. Every later read of the client reports client_secret: null. Public clients (token_endpoint_auth_method: "none") are issued no secret at all, so their create response also carries null.

Create a new OAuth client for API access. OAuth clients enable: - Third-party application integration - Service-to-service authentication - Mobile app authentication - CLI tool access **Choosing the Right Grant Type:** | Use Case | Grant Type | PKCE | Notes | |----------|------------|------|-------| | Web app with backend | `authorization_code` | Optional | Most secure for user-facing apps | | Mobile/Desktop app | `authorization_code` | Required | Public client, no secret storage | | Server-to-server | `client_credentials` | No | For automated services, no user context | | Single-page app | `authorization_code` | Required | Use PKCE instead of implicit | | Long-lived sessions | Add `refresh_token` | - | Combine with primary grant type | **Grant Type Details:** - **authorization_code**: User authorizes app via browser, app exchanges code for tokens - **client_credentials**: Service authenticates directly with client_id/secret (no user) - **refresh_token**: Exchange refresh token for new access token (add to other grants) - **implicit**: *Deprecated* - Use authorization_code + PKCE instead **PKCE Support**: - Enable PKCE for public clients (mobile apps, SPAs) - Supports S256 (SHA-256) and plain challenge methods - Required for clients without client secrets **`type` — user client or service account:** `type` accepts exactly `"user"` (the default) or `"project"`, and decides whose permissions the client carries. Any other value is rejected with `422`. - `"user"`: the client acts as the user who created it and inherits that user's permissions. Only that user is made an owner of the client. - `"project"`: a service account is created for the client, so it carries project-level permissions rather than one person's, and every member of the project is granted viewer access to the client. Use this for automation that must keep working after the creating user leaves. `type` is not echoed back: it appears on no response field, so read it back from behaviour rather than from the created object. **Fields silently ignored:** the request model is `UserOAuthClientCreate`. Any key it does not declare is dropped rather than rejected — notably `scopes`, `profile` and `access_token_type`, which appeared in older references. Scopes are fixed at `offline_access` and the access token type at `opaque`; sending different values changes nothing and the create still returns `200`. `client_secret` is returned only once, in this response — store it securely. Every later read of the client reports `client_secret: null`. Public clients (`token_endpoint_auth_method: "none"`) are issued no secret at all, so their create response also carries `null`.

Authentication

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

AuthorizationBearer

API key or access token, sent as Authorization: Bearer <token>. The simplest option: create an API key in your dashboard under Settings, then paste it here.

Path parameters

org_idstringRequiredformat: "uuid"

The unique identifier of the organization.

project_idstringRequiredformat: "uuid"

The unique identifier of the project.

Request

This endpoint expects an object.

namestringRequired

Name for the new OAuth client.

descriptionstring or nullOptional

Optional description of the client's purpose.

redirect_urislist of strings or nullOptional

List of authorized redirect URIs. Required if using authorization_code or implicit grant types.

grant_typeslist of enums or nullOptional

List of OAuth grant types to enable.

typeenumOptionalDefaults to user

Type of OAuth client to create:

user: Standard client tied to creating user’s permissions
project: Service account client with project-level permissions

token_endpoint_auth_methodenumOptionalDefaults to client_secret_basic

Authentication method for the client:

client_secret_basic: Client ID and secret sent in HTTP headers
client_secret_post: Client ID and secret sent in request body
none: No client authentication (required for public clients using PKCE)

pkce_requiredbooleanOptionalDefaults to false

Whether to require PKCE (Proof Key for Code Exchange) for authorization code flows. PKCE enhances security by requiring code_challenge and code_verifier parameters. IMPORTANT: Only applicable when ‘authorization_code’ is included in grant_types. Strongly recommended for public clients (mobile apps, SPAs) and beneficial for all clients.

pkce_challenge_methodenumOptional

PKCE code challenge method when PKCE is enabled.

S256: SHA256 hash of code verifier (recommended and secure)
plain: Plain text code verifier (not recommended, only for testing)

Response

OAuth client created

idstringformat: "uuid"

Unique identifier for the OAuth client.

namestring

Human-readable name for the OAuth client.

client_idstringformat: "uuid"

Unique identifier used to identify the client with the authorization server.

project_idstringformat: "uuid"

ID of the project this OAuth client belongs to.

createdstring

Timestamp when the OAuth client was created.

modifiedstring

Timestamp when the OAuth client was last modified.

descriptionstring or nullOptional

Optional description explaining the client's purpose and usage.

redirect_urislist of strings or nullOptional

List of authorized redirect URIs for OAuth flows requiring user interaction. Required for authorization code and implicit flows. Must be exact matches when used. Must use HTTPS in production (except for localhost).

grant_typeslist of enums or nullOptional

OAuth 2.0 grant types enabled for this client.

client_credentials: For server-to-server API access
authorization_code: For web and mobile apps
refresh_token: For maintaining long-term access
implicit: Legacy flow, not recommended for new applications

client_secretstring or nullOptional

Secret key used to authenticate the client. Only shown once upon creation. Must be stored securely. Required for confidential clients (e.g., server applications).

token_endpoint_auth_methodenumOptionalDefaults to client_secret_basic

Authentication method enabled for the client:

client_secret_basic: Client ID and secret sent in HTTP headers
client_secret_post: Client ID and secret sent in request body
none: No client authentication (required for public clients using PKCE)

pkce_requiredbooleanOptionalDefaults to false

Whether PKCE (Proof Key for Code Exchange) is required for this client. When enabled, authorization code flows must include code_challenge and code_verifier. Recommended for public clients (mobile apps, SPAs) and enhances security for all clients.

pkce_challenge_methodenum or nullOptionalDefaults to S256

PKCE code challenge method when PKCE is enabled.

S256: SHA256 hash of code verifier (recommended and secure)
plain: Plain text code verifier (not recommended, only for testing)

deletedstring or nullOptional

Timestamp when the OAuth client was deleted, if applicable.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

Use Case

Grant Type

PKCE

Notes

Web app with backend

authorization_code

Optional

Most secure for user-facing apps

Mobile/Desktop app

authorization_code

Required

Public client, no secret storage

Server-to-server

client_credentials

For automated services, no user context

Single-page app

authorization_code

Required

Use PKCE instead of implicit

Long-lived sessions

Add refresh_token

Combine with primary grant type