OAuth 2.0 Integration

OAuth Flow Overview

Authorization Request

Redirect users to OrbitForms authorization page

User Consent

User reviews and approves requested permissions

Authorization Code

OrbitForms redirects back with an authorization code

Token Exchange

Exchange the code for access and refresh tokens

API Access

Use the access token to make API requests

Step 1: Build Authorization URL

Redirect users to the OrbitForms 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

Parameter	Description
`client_id`	Your application’s Client ID
`redirect_uri`	Must match a registered callback URL
`response_type`	Always “code” for authorization code flow
`scope`	Space-separated list of requested permissions
`state`	Random 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

submissions:delete

Delete submissions

contacts:read

Read contacts and tags

contacts:write

Create, update, and manage contacts and tags

contacts:delete

Delete contacts

team:read

Read team information

team:write

Update team settings

team:members

Manage team members

webhooks:read

Read webhook configurations

webhooks:write

Create and manage webhooks

scheduling:read

Read scheduling pages, event types, and availability

scheduling:write

Create and update scheduling pages and event types

scheduling:delete

Delete scheduling pages and event types

meetings:read

Read meetings

meetings:write

Update meetings (status changes, notes)

meetings:delete

Delete meetings

sequences:read

Read sequences, steps, enrollments, analytics, and unsubscribes

sequences:write

Enroll contacts and manage unsubscribes

sequences:delete

Unenroll contacts and remove unsubscribes

analytics:read

Read form analytics

user:read

Read user profile

user:write

Update user profile

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

​OAuth Flow Overview

​Step 1: Build Authorization URL

​Step 2: Exchange Code for Tokens

​Available Scopes