Overview
Login and authentication of the API.
Sign-in for external applications (OAuth 2.1 authorization code with PKCE)
An application that signs users in on their behalf does not collect passwords. It is
provisioned on the instance as a public client with a fixed list of callback URIs and
receives a client_id; there is no client secret. The flow:
- Create a PKCE pair: a random
code_verifierand itscode_challenge(BASE64URL(SHA256(code_verifier)), methodS256;plainis rejected). - Send the user to
GET /authorizewithresponse_type=code, yourclient_id, one of your registeredredirect_uris (matched character by character, https only),scope=customer-api, astateof your own and thecode_challengewithcode_challenge_method=S256. The user signs in there with the credentials of the instance or with its single sign-on. If your application is served under the address of the instance and the user is already signed in to its web app in the same browser, the user only confirms once per application to continue with that account and is signed in without being asked from then on. Served from another address, the browser usually does not share that sign-in and the user signs in as described. Discovery:GET /.well-known/oauth-authorization-server. - The instance redirects to your callback with
codeand yourstate. - Exchange the code at
POST /customer-api/v1/auth_tokenwithgrant_type=authorization_code,code,redirect_uri,client_idandcode_verifier. The answer carries an access token and a refresh token; renew withgrant_type=refresh_token.
Every call with that token is limited to what the signed-in user may do and to the features
of the instance. The application is approved for the customer-api scope only. To get an
application provisioned, contact support
with its name and its https callback URIs.

