Authentication

Making Authenticated Requests

Include the access token in the Authorization header of your API requests:

curl -X GET "https://app.useorbitcrm.ai/api/v1/forms" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Token Expiration

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring the user to re-authorize.

To refresh an expired access token:

curl -X POST "https://app.useorbitcrm.ai/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

The response has the same shape as the first token response, including team_id, with a new refresh token: refresh tokens rotate on every use. Replace the stored pair as soon as the response arrives. The old refresh token keeps working for 60 seconds after its first use (so a retry of a request that timed out still succeeds); after that, using it again answers 400 invalid_grant and the person has to authorize again. Refresh tokens expire 30 days after they are issued, so an app that refreshes at least monthly never loses its connection.

Authentication Errors

Status	Error	Solution
`401`	`invalid_token`	Token is expired or invalid. Refresh the token.
`401`	`token_expired`	Use your refresh token to get a new access token.
`403`	`insufficient_scope`	Request additional scopes from the user.
`429`	`rate_limit_exceeded`	Too many requests. Wait for `Retry-After` and back off.

Best Practices

Store tokens securely

Never expose tokens in client-side code or logs.

Proactively refresh

Refresh tokens before they expire to avoid interruptions.

Handle errors gracefully

Implement proper error handling for auth failures.

Next Steps

App Permissions

Learn about available scopes

API Reference

Make your first API call

Getting Started

Building Apps

Publishing

App Resources

Making Authenticated Requests

Token Expiration

Authentication Errors

Best Practices

Store tokens securely

Proactively refresh

Handle errors gracefully

Next Steps

App Permissions

API Reference

​Making Authenticated Requests

​Token Expiration

​Authentication Errors

​Best Practices

Store tokens securely

Proactively refresh

Handle errors gracefully

​Next Steps

App Permissions

API Reference

Making Authenticated Requests

Token Expiration

Authentication Errors

Best Practices

Next Steps