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

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

Getting Started

Building Apps

Publishing

App Resources

OAuth 2.0 Integration

OAuth Flow Overview

Step 1: Build Authorization URL

Step 2: Exchange Code for Tokens

Available Scopes

forms:read

forms:write

forms:delete

submissions:read

submissions:write

contacts:read

contacts:write

contacts:delete

webhooks:read

webhooks:write

analytics:read

Security Best Practices

Keep secrets secure

Use state parameter

Handle token refresh

Validate redirect URIs

Next Steps

App Permissions

API Reference

​OAuth Flow Overview

​Step 1: Build Authorization URL

​Step 2: Exchange Code for Tokens

​Available Scopes

forms:read

forms:write

forms:delete

submissions:read

submissions:write

contacts:read

contacts:write

contacts:delete

webhooks:read

webhooks:write

analytics:read

​Security Best Practices

Keep secrets secure

Use state parameter

Handle token refresh

Validate redirect URIs

​Next Steps

App Permissions

API Reference

OAuth Flow Overview

Step 1: Build Authorization URL

Step 2: Exchange Code for Tokens

Available Scopes

Security Best Practices

Next Steps