Client Credentials & OAuth
Corral provides OAuth 2.0 client credentials for programmatic access to the platform API. This enables automated workflows, custom integrations, and third-party applications to interact with Corral without a user login.
Creating Client Credentials
Client credentials can be created at the project or app level:
Via API
POST /api/projects/{slug}/client-credentials
POST /api/apps/{slug}/client-credentialsThis returns a clientId and clientSecret. Store the secret securely — it’s only shown once.
Scopes
Two scopes control what the credentials can access:
| Scope | What It Grants |
|---|---|
| Management | Access to management APIs — configuration, publishing, analytics |
| Consumer | Access to consumer-facing APIs — sending messages, reading conversations |
Choose the scope that matches your use case. A CI/CD pipeline that publishes agent versions needs Management. A custom chat client needs Consumer.
Using Client Credentials
Get an Access Token
Use the OAuth 2.0 client credentials grant to get a bearer token:
This section is a work in progress.
Make API Requests
Include the token in every request:
Authorization: Bearer {access_token}Secret Rotation
Rotate a client secret without downtime:
POST /api/{projects|apps}/{slug}/client-credentials/{clientId}/regenerate-secretThis generates a new secret. The old secret is invalidated immediately.
Permissions
Client credentials are permission subjects — they receive the same per-node permissions as users. When you create credentials on an app, those credentials inherit the permission scope of that app.
Use Cases
- CI/CD integration — publish agent versions as part of your deployment pipeline
- Custom chat clients — build your own UI that sends and receives messages via the API
- Monitoring and reporting — pull analytics data into your existing dashboards
- Automated workflows — trigger agent interactions from external systems
- Testing — automated test suites that exercise agent behavior