Authorize or re-authorize a connection
GET/unified/integration/auth/{workspace_id}/{integration_type} NO AUTH NEEDED
Returns an authorization URL for the specified integration. After successful authorization, a new connection is created unless connection_id and reauth_token are provided, in which case the existing connection is updated in place.
Parameters
success_redirectstring
The URL where you want the user to be redirect to after a successful authorization. The connection ID will be appended with (id=<connectionId>) to this URL, as will the state that was provided.
failure_redirectstring
The URL where you want the user to be redirect to after an unsuccessful authentication. An "error" variable will be appended.
statestring
Extra state to send back to your success URL
external_xrefstring
Your user identifier to associate with the new Integration
scopesstring array
redirectboolean
envstring default=Production
langstring
Language: en, fr, es, it, pt, zh, hi
subdomainstring
Optional tenant domain or subdomain for integrations that require it to build the authorize, token, or API URL. Depending on the integration, this may be a bare subdomain or a full domain/URL.
regionstring
Optional region index (into the integration api.urls array) selected by the end-user. Set automatically by the auth widget when the workspace integration has prompt_region=true.
connection_idstring
Existing connection ID to re-authorize in place instead of creating a duplicate. Requires reauth_token.
reauth_tokenstring
Single-use token from "Create a re-authorization token for a connection" (POST /unified/connection/{id}/reauth); required with connection_id.
workspace_idstring required
The ID of the workspace
integration_typestring required
Type of the supported integration
Returns
string
Errors
Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Too many requests to unified.to API; max requests per minute: N"
}| Status | Error | Meaning |
|---|---|---|
400 | Bad Request | The request was malformed or failed validation. |
401 | Unauthorized | The connection is likely broken; re-authorize it. |
403 | Forbidden | The connection is missing permissions or scopes. |
404 | Not Found | The requested resource does not exist. |
429 | Too Many Requests | Rate limit exceeded (see the two sources below). |
500 | Internal Server Error | An unexpected error occurred. |
501 | Not Implemented | Not supported by this integration. |
Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.
429 Too Many Requests
A 429 has two possible sources:
- The integration's own rate limit, passed through.
- Unified's workspace limit: a rolling 60 seconds, set by plan, with the message
Too many requests to unified.to API; max requests per minute: N.
Are we missing anything? Let us know