> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitforms.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

<Steps>
  <Step title="Authorization Request">
    Redirect users to OrbitForms authorization page
  </Step>

  <Step title="User Consent">
    User reviews and approves requested permissions
  </Step>

  <Step title="Authorization Code">
    OrbitForms redirects back with an authorization code
  </Step>

  <Step title="Token Exchange">
    Exchange the code for access and refresh tokens
  </Step>

  <Step title="API Access">
    Use the access token to make API requests
  </Step>
</Steps>

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

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

```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"
}
```

## Available Scopes

Request only the permissions your app needs:

<CardGroup cols={2}>
  <Card title="forms:read">
    Read form configurations
  </Card>

  <Card title="forms:write">
    Create and update forms
  </Card>

  <Card title="forms:delete">
    Delete forms
  </Card>

  <Card title="submissions:read">
    Read form submissions
  </Card>

  <Card title="submissions:write">
    Update submission data
  </Card>

  <Card title="contacts:read">
    Read contacts and tags
  </Card>

  <Card title="contacts:write">
    Create, update, and manage contacts and tags
  </Card>

  <Card title="contacts:delete">
    Delete contacts
  </Card>

  <Card title="webhooks:read">
    Read webhook configurations
  </Card>

  <Card title="webhooks:write">
    Create and manage webhooks
  </Card>

  <Card title="analytics:read">
    Read form analytics
  </Card>
</CardGroup>

## Security Best Practices

<CardGroup cols={1}>
  <Card title="Keep secrets secure" icon="lock">
    Never expose your Client Secret in client-side code or version control.
  </Card>

  <Card title="Use state parameter" icon="key">
    Always include a random state string to prevent CSRF attacks.
  </Card>

  <Card title="Handle token refresh" icon="clock">
    Use refresh tokens to get new access tokens before they expire.
  </Card>

  <Card title="Validate redirect URIs" icon="alert-triangle">
    Only use pre-registered callback URLs to prevent open redirect vulnerabilities.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="App Permissions" icon="shield" href="/apps/permissions">
    Learn about permission scopes
  </Card>

  <Card title="API Reference" icon="key" href="/developers/api/overview">
    Explore available endpoints
  </Card>
</CardGroup>