Skip to main content
POST
/
oauth
/
apps
Create a new OAuth application
curl --request POST \
  --url http://sandbox.mintlify.com/oauth/apps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "My Integration",
  "scopes": [
    "read:organization",
    "write:organization"
  ],
  "description": "Integration for managing organization data",
  "redirectUri": "https://example.com/callback"
}
'
Creates a new OAuth2 application for your organization. Only OWNERS and ADMINS can create OAuth apps.
The client secret is returned ONCE in the response. Store it securely immediately - it cannot be retrieved later!

​
Permissions

Only OWNERS and ADMINS can create OAuth applications.

​
Request Body

FieldTypeRequiredDescription
namestringYesApplication name (1-100 characters)
descriptionstringNoApplication description (max 500 characters)
redirectUristringNoRedirect URI for OAuth flow
scopesarrayYesOAuth scopes requested

​
Available Scopes

  • read:user - Read user information
  • write:user - Modify user information
  • read:organization - Read organization data
  • write:organization - Modify organization data
  • read:members - Read member information
  • write:members - Modify members
  • read:webhooks - Read webhook configuration
  • write:webhooks - Manage webhooks
  • admin:organization - Full organization admin access
  • admin:all - Full system access

​
Example Request

curl -X POST http://localhost:3001/api/oauth/apps \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "description": "Integration for managing organization data",
    "redirectUri": "https://example.com/callback",
    "scopes": ["read:organization", "write:organization"]
  }'

​
Example Response

{
  "clientId": "app_1234567890abcdef",
  "clientSecret": "cs_1234567890abcdef",
  "name": "My Integration",
  "description": "Integration for managing organization data",
  "redirectUri": "https://example.com/callback",
  "scopes": ["read:organization", "write:organization"],
  "isActive": true,
  "createdAt": "2025-01-26T10:00:00Z"
}

​
Security Notes

  • The clientSecret is only returned once during creation
  • Store the secret securely (environment variables, secret manager)
  • Never commit secrets to version control
  • Rotate secrets if compromised

​
Common Errors

​
400 Bad Request

Invalid input data or validation errors.

​
401 Unauthorized

Authentication required.

​
403 Forbidden

Only owners and admins can create OAuth applications.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Application name

Required string length: 1 - 100
Example:

"My Integration"

​
scopes
enum<string>[]
required

OAuth scopes requested

Available options:
read:user,
write:user,
read:organization,
write:organization,
read:members,
write:members,
read:webhooks,
write:webhooks,
admin:organization,
admin:all
Example:
["read:organization", "write:organization"]
​
description
string

Application description

Maximum string length: 500
Example:

"Integration for managing organization data"

​
redirectUri
string

Redirect URI for OAuth flow

Example:

"https://example.com/callback"

Response

OAuth application created successfully. Client secret returned only once - save it immediately!