OAuth 2.0 Integration

Orbit AI uses OAuth 2.0 for secure authentication. This guide walks you through implementing the authorization code flow to access the Orbit AI API on behalf of users.

OAuth Flow Overview

Authorization Request

Redirect users to Orbit AI authorization page

User Consent

User reviews and approves requested permissions

Authorization Code

Orbit AI 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 Orbit AI authorization endpoint with the following parameters:

Authorization URL

https://orbitforms.ai/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:

Token Request

curl -X POST https://orbitforms.ai/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

submissions:read

Read form submissions

submissions:write

Submit to forms

team:read

Read team information

webhooks:manage

Manage webhook configurations

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