> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorbitcrm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0 Integration

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

## OAuth Flow Overview

**1. Authorization Request**

Redirect users to OrbitForms authorization page

**2. User Consent**

User reviews and approves requested permissions

**3. Authorization Code**

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

```bash theme={null}
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:**

```json theme={null}
{
  "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.

> [!NOTE]
>
> **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.

```bash theme={null}
curl https://app.useorbitcrm.ai/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={null}
{
  "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](https://docs.useorbitcrm.ai/apps/permissions.md) groups the same scopes by area.

> [card] forms:read
>
> View your forms, their fields and settings

> [card] forms:write
>
> Create and update forms

> [card] forms:delete
>
> Delete forms

> [card] submissions:read
>
> View form submissions and the answers people gave

> [card] submissions:write
>
> Change the answers stored on form submissions

> [card] submissions:delete
>
> Delete form submissions and the files uploaded with them

> [card] contacts:read
>
> View your contacts, their tags and your contact imports

> [card] 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

> [card] contacts:delete
>
> Delete contacts

> [card] crm:read
>
> View pipelines, stages, custom fields, CRM settings, saved views, your workspace members and teams (member groups), and who can see each pipeline

> [card] 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

> [card] companies:read
>
> View your companies

> [card] companies:write
>
> Create, update and merge companies; a merge moves the duplicate company to Recently deleted

> [card] companies:delete
>
> Delete companies

> [card] deals:read
>
> View deals, their contacts and stage history, and pipeline totals

> [card] 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

> [card] deals:delete
>
> Delete deals

> [card] tasks:read
>
> View tasks

> [card] tasks:write
>
> Create, update, complete and delete tasks

> [card] notes:read
>
> View notes on contacts, companies and deals, and comments on notes and logged activity

> [card] notes:write
>
> Create, edit and delete notes, and comment on notes and logged activity

> [card] 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

> [card] 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

> [card] files:read
>
> View the files on contacts, companies and deals and download them

> [card] files:write
>
> Attach files to contacts, companies and deals, fetch files from URLs you provide into the workspace, and delete files

> [card] workflows:read
>
> View workflows, their runs and AI agent templates

> [card] 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

> [card] workflows:delete
>
> Delete workflows and AI agent templates

> [card] 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

> [card] 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

> [card] meetings:read
>
> View meetings and who they are with

> [card] 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

> [card] meetings:delete
>
> Delete meetings

> [card] scheduling:read
>
> View scheduling pages, event types, availability schedules and open booking slots

> [card] scheduling:write
>
> Create and update scheduling pages and event types

> [card] scheduling:delete
>
> Delete scheduling pages and event types

> [card] sequences:read
>
> View email sequences, their steps, enrollments, analytics and unsubscribes, and email templates and snippets

> [card] 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

> [card] 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

> [card] sequences:delete
>
> Remove contacts from email sequences

> [card] 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

> [card] emails:send
>
> Send emails to your contacts from your Orbit sending address. Each email reaches someone outside the workspace and can't be unsent

> [card] webhooks:read
>
> View webhook subscriptions and the URLs they deliver to

> [card] 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

> [card] integrations:read
>
> See which apps are connected to your workspace and whether they are syncing. Never their passwords, keys or tokens

> [card] team:read
>
> View your workspace's name and URL slug

> [card] analytics:read
>
> View form analytics: views, submissions and conversion rates, by day and by traffic source, device and country

> [card] user:read
>
> View your name and email address

## Security Best Practices

> [card] Keep secrets secure
>
> Never expose your Client Secret in client-side code or version control.

> [card] Use state parameter
>
> Always include a random state string to prevent CSRF attacks.

> [card] Handle token refresh
>
> Use refresh tokens to get new access tokens before they expire.

> [card] Validate redirect URIs
>
> Only use pre-registered callback URLs to prevent open redirect vulnerabilities.

## Next Steps

> [card] [App Permissions](https://docs.useorbitcrm.ai/apps/permissions.md)
>
> Learn about permission scopes

> [card] [API Reference](https://docs.useorbitcrm.ai/developers/api/overview.md)
>
> Explore available endpoints


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.