Skip to main content

​
OAuth Flow Overview

1

Authorization Request

Redirect users to Orbit AI authorization page
2

User Consent

User reviews and approves requested permissions
3

Authorization Code

Orbit AI redirects back with an authorization code
4

Token Exchange

Exchange the code for access and refresh tokens
5

API Access

Use the access token to make API requests

​
Step 1: Build Authorization URL

Redirect users to the Orbit AI authorization endpoint with the following parameters: 
https://orbitforms.ai/api/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=forms:read forms:write submissions:read&
  state=RANDOM_STATE_STRING
ParameterDescription
client_idYour application’s Client ID
redirect_uriMust match a registered callback URL
response_typeAlways “code” for authorization code flow
scopeSpace-separated list of requested permissions
stateRandom string for CSRF protection

​
Step 2: Exchange Code for Tokens

After the user authorizes your app, they’ll be redirected to your callback URL with an authorization code. Exchange this code for access and refresh tokens: 
curl -X POST https://orbitforms.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"
Response: 
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "scope": "forms:read forms:write submissions:read"
}

​
Available Scopes

Request only the permissions your app needs:

forms:read

Read form configurations

forms:write

Create and update forms

forms:delete

Delete forms

submissions:read

Read form submissions

submissions:write

Update submission data

contacts:read

Read contacts and tags

contacts:write

Create, update, and manage contacts and tags

contacts:delete

Delete contacts

webhooks:read

Read webhook configurations

webhooks:write

Create and manage webhooks

analytics:read

Read form analytics

​
Security Best Practices

Keep secrets secure

Never expose your Client Secret in client-side code or version control.

Use state parameter

Always include a random state string to prevent CSRF attacks.

Handle token refresh

Use refresh tokens to get new access tokens before they expire.

Validate redirect URIs

Only use pre-registered callback URLs to prevent open redirect vulnerabilities.

​
Next Steps

App Permissions

Learn about permission scopes

API Reference

Explore available endpoints