Summary
OAuth Apps allow external applications to securely connect to Astra on behalf of users. Instead of sharing credentials, users sign in to Astra and explicitly grant permission to the application. This guide explains how OAuth Apps work, how to create and manage them, and when to use OAuth Apps instead of API Keys.
Instructions
What is an OAuth App?
An OAuth App is an application that you register in Astra to allow users to securely authorize access to their Workspace.
When you create an OAuth App, Astra generates:
A Client ID, which identifies your application.
A Client Secret, which authenticates your application.
When a user connects your application to Astra, they are redirected to Astra to sign in and review the permissions your application is requesting. Access is granted only after the user approves the request.
Recommended use cases
OAuth Apps are ideal for:
SaaS products that connect to a customer's Astra account
Applications that require user consent before accessing Astra data
Multi-tenant applications that serve multiple customers or Workspaces
Integrations that allow users to connect their Astra account through a Connect Astra button
When not to use OAuth Apps
OAuth Apps may not be the best choice for:
Internal scripts and backend automation
System-to-system integrations without user interaction
Scheduled jobs running under a single organization account
For these scenarios, API Keys are typically simpler to manage.
How to create an OAuth App
To create an OAuth App:
Log into your Astra account.
Go to Account > OAuth Apps.
Click Create App.
Enter the required details:
App Name – The name displayed to users during authorization.
Redirect URI – The URL where users are sent after approving access.
Scopes – The permissions your application requires.
Click Create.
Important: Save your Client Secret immediately
After the app is created, Astra displays the Client Secret only once.
Copy and store the Client ID and Client Secret in a secure location before leaving the page.
Afterward, Astra will continue to display the Client ID, but the full Client Secret cannot be viewed again.
Understand Redirect URIs
A Redirect URI is the destination where Astra sends users after they approve or deny access to your application.
The Redirect URI provided during authorization must exactly match one of the Redirect URIs registered for the OAuth App. If the values do not match, the authorization request will fail.
Example Redirect URIs
Production environment:
https://your-app.com/oauth/callback
Local development environment:
http://localhost:8787/callback
Understand scopes
Scopes define the permissions your application can request from Astra.
Users can review these permissions before deciding whether to authorize your application.
Available scopes
Scope | Description |
All | Full access to all available public API capabilities |
Chat | Chat with Agents |
Agents: Read | View Agents |
Agents: Write | Create, update, and manage Agents |
Contacts: Read | View contacts |
Contacts: Write | Create, update, and manage contacts |
Conversations: Read | View conversation history |
Knowledge: Read | View knowledge bases |
Knowledge: Write | Create, update, and manage knowledge bases |
Webhooks: Manage | Create and manage webhooks |
Analytics: Read | Access analytics data |
Best practice when working with Outh apps
Request only the permissions you need
Only request the scopes required for your application's functionality.
Requesting fewer permissions helps users understand what your application can access and improves trust during the authorization process.
How the authorization flow works (user experience)
When a user connects your OAuth App to Astra:
The user clicks Connect Astra in your application.
The user is redirected to Astra's authorization page.
Astra displays the application name and requested permissions.
The user signs in to Astra if they are not already signed in.
The user clicks Authorize or Deny.
If approved, Astra redirects the user to the configured Redirect URI.
Your application receives authorization credentials and can access Astra on behalf of the user.
What this means for users
Users never need to share their Astra password with your application.
Each user grants access individually.
Access applies only to the Workspace the user authorizes.
Users can remove access at any time by disconnecting the application.
Manage OAuth Apps
The OAuth Apps page displays all registered applications.
You can review existing apps and remove applications that are no longer needed.
How to delete an OAuth App
To delete an OAuth App:
Log into your Astra account.
Open Account → OAuth Apps.
Locate the application you want to remove.
Delete the application.
Confirm the action.
What happens when an app is deleted?
When an OAuth App is deleted:
New authorization requests can no longer be started.
Existing access tokens are revoked.
Connected users lose access immediately.
Users must reconnect if a replacement app is created.
OAuth Apps vs. API Keys
Which option should you choose?
Use the following table to determine which authentication method is best for your use case.
| OAuth Apps | API Keys |
Intended users | Customers and end users | Internal systems and backend services |
User authorization required | Yes | No |
User consent screen | Yes | No |
Supports multiple customers | Yes | No |
Credential type | Short-lived access tokens that can be refreshed | Long-lived API Keys |
Typical use case | "Connect your Astra account" integration | Automated data sync or internal workflow |
Use OAuth Apps when users need to connect their Astra account and grant permission to your application.
Use API Keys when you are building internal automations, backend services, or integrations that operate without user interaction.