Docs
Developer Console
OAuth

The auth link

GET/v1/oauth/authorize

The auth link. Send a user here to connect a website account to your application. The connect site, rather than the API, serves this page. It shows your application's name and icon and the website, asks the user to approve, and signs them in. It then redirects to redirect_uri with code and state, or with error (access_denied when the user declines, server_error when the sign-in fails) and state. An authorization expires 15 minutes after it starts; a code must be exchanged within 30 minutes. PKCE (code_challenge with S256) is optional for every client and recommended for public ones, because without a secret it is the only thing that ties the code exchange to the app that started it.

Query Parameters

client_id*string

The application id.

Formatuuid
redirect_uri*string

One of the application's registered redirect URIs, matched exactly.

Formaturi
response_type*"code"

Value in

  • "code"
state*string

An opaque value your application generates per request and checks on return.

Length1 <= length <= 1024
website*string

The website the user will sign in to, as an HTTPS URL or a hostname (mail.google.com).

Lengthlength <= 500
code_challenge?string

The S256 PKCE challenge. Optional; recommended for public applications.

Length43 <= length <= 128
code_challenge_method?"S256"

Value in

  • "S256"
external_user_id?string

Your own id for the user. Confidential applications only.

Length1 <= length <= 255

Response Body

text/html

curl -X GET "https://example.com/v1/oauth/authorize?client_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&redirect_uri=http%3A%2F%2Fexample.com&response_type=code&state=string&website=string"
"string"

Conventions

How the API is shaped, so the generated reference reads without surprises.

Exchange a code for a token POST

Exchanges an authorization code for a connection access token. If your application is public, send `client_id` in the form body, plus the PKCE `code_verifier` when you sent a `code_challenge` on the auth link. If it's confidential, authenticate with HTTP Basic `client_id:client_secret`. The token is long-lived and doesn't refresh; issuing a new one for the same connection revokes the previous one. An invalid, expired, or used code returns `400 invalid_grant`.