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://app.useorbitcrm.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://app.useorbitcrm.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",
  "team_id": "7c1d0e2f-..."
}

team_id is the workspace the person connected: the team_id on every record and webhook envelope. Store it with the tokens to tell one connected workspace from another; a person with several workspaces picks one on the consent screen, and a later authorization from the same person may name a different one.

Confidential and public clients. An app registered in the Developer Portal has a client_secret and sends it on every token request, as above. A public client (no secret, such as an MCP client that registered itself) must use PKCE instead: send code_challenge and code_challenge_method=S256 on the authorization request and code_verifier on the token request. A confidential client may add PKCE as well.

Step 3: Identify the Workspace

GET /api/v1/me returns the workspace and person behind a token, and the token’s scopes. Request team:read for the workspace’s name and slug and user:read for the person’s email and name; the ids come back either way.

curl https://app.useorbitcrm.ai/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": {
    "team": { "id": "7c1d0e2f-...", "name": "Acme", "slug": "acme" },
    "user": { "id": "d4e5f6a7-...", "email": "sam@acme.com", "name": "Sam Rivera" },
    "credential": { "type": "oauth", "scopes": ["team:read", "user:read", "deals:read"], "app": { "id": "YOUR_APP_ID", "client_id": "YOUR_CLIENT_ID", "name": "Your app" } }
  }
}

Available Scopes

Request only the permissions your app needs. App Permissions groups the same scopes by area.

forms:read

View your forms, their fields and settings

forms:write

Create and update forms

forms:delete

Delete forms

submissions:read

View form submissions and the answers people gave

submissions:write

Change the answers stored on form submissions

submissions:delete

Delete form submissions and the files uploaded with them

contacts:read

View your contacts, their tags and your contact imports

contacts:write

Create, update, import and merge contacts and manage tags. An import can overwrite existing contacts’ details and add the companies and tags it names; a merge archives the duplicate contact

contacts:delete

Delete contacts

crm:read

View pipelines, stages, custom fields, CRM settings, saved views, your workspace members and teams (member groups), and who can see each pipeline

crm:write

Create, change and remove pipelines, stages, custom fields, saved views and teams (member groups); change CRM settings and who can see each pipeline

companies:read

View your companies

companies:write

Create, update and merge companies; a merge moves the duplicate company to Recently deleted

companies:delete

Delete companies

deals:read

View deals, their contacts and stage history, and pipeline totals

deals:write

Create, update and merge deals, move them between stages, and add or remove the contacts on a deal; a merge moves the duplicate deal to Recently deleted

deals:delete

Delete deals

tasks:read

View tasks

tasks:write

Create, update, complete and delete tasks

notes:read

View notes on contacts, companies and deals, and comments on notes and logged activity

notes:write

Create, edit and delete notes, and comment on notes and logged activity

activities:read

View each record’s timeline and the logged and synced emails on it (including email synced from members’ connected Gmail or Outlook mailboxes), calls, meetings, messages and notes, including email bodies, and activity imports

activities:write

Log, edit and delete emails, calls, meetings and messages on contacts, companies and deals, and import activity history in bulk; an admin can undo an import, which deletes everything it created. Nothing is sent: these record what already happened

files:read

View the files on contacts, companies and deals and download them

files:write

Attach files to contacts, companies and deals, fetch files from URLs you provide into the workspace, and delete files

workflows:read

View workflows, their runs and AI agent templates

workflows:write

Create, update, activate, pause and run workflows, and manage AI agent templates. Active and running workflows carry out their steps, which can email people, enroll contacts in sequences, change CRM records and send data to connected apps and webhooks

workflows:delete

Delete workflows and AI agent templates

dialer:read

View dialer settings, the workspace’s phone numbers and who each is assigned to, calling costs, call lists, dialing sessions, calls with their outcomes and notes, call statistics, call transcripts and AI coaching feedback, call scripts, voicemail greeting details and the do-not-call list

dialer:write

Change dialer settings (including turning call recording, paid transcription and AI feedback on or off), assign the workspace’s phone numbers to members, set call outcomes and notes, write and delete call scripts, permanently delete call recordings and transcripts, and add or remove do-not-call numbers. Never places calls, buys numbers or changes billing

meetings:read

View meetings and who they are with

meetings:write

Book meetings on your team’s calendars, which sends calendar invites to the attendee, and change a meeting’s status (including cancelling it, which tells the attendee) and notes

meetings:delete

Delete meetings

scheduling:read

View scheduling pages, event types, availability schedules and open booking slots

scheduling:write

Create and update scheduling pages and event types

scheduling:delete

Delete scheduling pages and event types

sequences:read

View email sequences, their steps, enrollments, analytics and unsubscribes, and email templates and snippets

sequences:write

Enroll contacts in email sequences, which then emails them, add addresses to the unsubscribe list, and create, edit and delete email templates and snippets

sequences:manage

Create email sequences, write and change their steps, settings and sender, and activate or pause them. An active sequence emails everyone enrolled in it

sequences:delete

Remove contacts from email sequences

emails:read

View the one-to-one emails your team sends contacts from Orbit: sender, recipient, subject, message and whether each was delivered, opened, replied to or bounced

emails:send

Send emails to your contacts from your Orbit sending address. Each email reaches someone outside the workspace and can’t be unsent

webhooks:read

View webhook subscriptions and the URLs they deliver to

webhooks:write

Create, change and delete webhooks that send events about forms, contacts, companies, deals, tasks, meetings and calls to any URL. Subscribing to an object also needs its read scope

integrations:read

See which apps are connected to your workspace and whether they are syncing. Never their passwords, keys or tokens

team:read

View your workspace’s name and URL slug

analytics:read

View form analytics: views, submissions and conversion rates, by day and by traffic source, device and country

user:read

View your name and email address

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

​Step 3: Identify the Workspace

​Available Scopes

forms:read

forms:write

forms:delete

submissions:read

submissions:write

submissions:delete

contacts:read

contacts:write

contacts:delete

crm:read

crm:write

companies:read

companies:write

companies:delete

deals:read

deals:write

deals:delete

tasks:read

tasks:write

notes:read

notes:write

activities:read

activities:write

files:read

files:write

workflows:read

workflows:write

workflows:delete

dialer:read

dialer:write

meetings:read

meetings:write

meetings:delete

scheduling:read

scheduling:write

scheduling:delete

sequences:read

sequences:write

sequences:manage

sequences:delete

emails:read

emails:send

webhooks:read

webhooks:write

integrations:read

team:read

analytics:read

user: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

Step 3: Identify the Workspace

Available Scopes

Security Best Practices

Next Steps