Authorize a connection

This method starts the OAuth authorization flow for a data connector. The platform returns an authorization URL. Redirect the user to this URL so they can grant access to their account.

After the user grants or denies access, the platform redirects them to the redirect URI you provided, with the outcome appended to that URI as query parameters. Read these parameters from the redirect that your application receives:

connection_id: The identifier of the new connection, returned on success. Store this value and pass it as the connection_id path parameter in later requests.
status: The ok value, returned on success.
custom_id: The label you supplied, returned on success when you provided one.
error: An error code, returned instead of the other parameters when the user denies access or the flow fails.

Authentication

x-api-keystring

Your API key.

Note

You can find your API key on the API Keys page.

Request

This endpoint expects an object.

providerenumRequired

The data connector provider to authorize.

Allowed values:

redirect_uristringRequiredformat: "uri"

The URI where the user is redirected after granting or denying access. By default, any redirect URI is accepted. If you’ve authorized specific redirect URIs with the Register a redirect URI method, this URI must be one of them.

custom_idstringOptional<=255 characters

A label you supplied, stored on the connection and returned with it. Use a value that does not identify a person so you can match the connection to your own records.

Response

The authorization flow has been successfully initiated.

authorize_urlstringOptional

The URL to redirect the user to so they can grant access.

statestringOptional

A value the platform uses to secure the authorization flow. You do not need to read or send it: the platform includes it in the authorize_url field and checks it automatically when the user is redirected back. It is returned only so you can match or troubleshoot requests.

Errors

400

Bad Request Error