You'll need an OAuth Client in order to use the inbound OAuth. Find out where and how to create them.

Endpoints

https://deskpro-instance.com/oauth/authorize

The authorize endpoint is the initial endpoint used in the inbound OAuth process. It is responsible for initiating the process of authorizing the client application to access protected resources on behalf of the user. The request parameters for this endpoint include the OAuth Client ID, response type, return URI, and any other parameters required for the specified response type. If the user associated with the OAuth Client is not already logged in, they will be redirected to authenticate via the app login. Once authenticated, the user is presented with the options to allow or cancel the request.

https://deskpro-instance.com/oauth/token

The token endpoint is used to exchange an authorization code for an access token, assuming the request is verified successfully. This is done by sending a request to the token endpoint with the authorization code, client ID, and client secret. If the request is verified, an access token is issued to the client application.

https://deskpro-instance.com/oauth/error

Most error handling is done via the League AuthorizationRequest, but the authorization and token issuing phases are also wrapped in an additional level of error handling.

Having encountered an error, the user should be redirected back to their specified redirect URI but, if this is not known, then they are redirected out of the process to a generic fallback error page with the error message.

Grant Flows

Authorization Code

Description

The auth code flow begins with the client application requesting authorization from the user. The authorization server then prompts the user to login and authorize the client application. If the user provides consent, the authorization server issues an authorization code to the client application.

The client application then exchanges the authorization code for an access token by sending a request to the token endpoint. If the authorization server verifies the request, it issues an access token to the client application.

Auth request params

Param	Type	Description
client_id	Required	The ID of the OAuth Client
response_type	Required	code
redirect_uri	Recommended	The redirect URL of the app, where auth responses will be sent. The URL must match one of the configured return URL’s on the client. If the client only has a single redirect URL configured, then this parameter is not mandatory. However, if there are multiple, then a return URL must be specified.
state	Recommended	A random string (typically 40 - 100 characters) which is included in the request and token response. Can be used by the client application to prevent CSRF attacks.

Successful auth response params

Param	Description
code	An authorisation code to be exchanged for the access token.
state	The string that was included in the request. This should be verified against the state value, stored prior to the request.

Token request params

Param	Type	Description
client_id	Required	The same OAuth Client ID from the request.
client_secret	Required	The Secret of the OAuth Client.
grant_type	Required	authorization_code
code	Required	The code from the auth request.
redirect_uri	Required	The same redirect URI from the request.

Successful token response params

Param	Description
access_token	The requested access token.
token_type	Bearer
expires_in	Token expiry time in seconds.
refresh_token	A refresh token. Can be used for to access the resource again when the current token expires.

Authorization Code + PKCE

Description

The auth code + PKCE flow is a more secure version of the authorization code flow. It is recommended for use in mobile and browser-based applications. The flow begins with the client application requesting authorization from the user. The authorization server then prompts the user to login and authorize the client application.

The user must generate a code verifier; a string 43-128 characters long, as defined in the RFC 7636 spec. The code verifier is then encoded (should use SHA-256); the result being the code challenge. The code challenge is sent as part of the auth request. If the user provides consent, the authorization server issues an authorization code to the client application.

The client application then exchanges the authorization code for an access token by sending a request to the token endpoint. This request must include the original code verifier, which is used to verify the request instead of using a client secret.

If the authorization server verifies the request, it issues an access token to the client application.

Auth request params

Param	Type	Description
client_id	Required	The ID of the OAuth Client
response_type	Required	code
redirect_uri	Recommended	The redirect URL of the app, where auth responses will be sent. The URL must match one of the configured return URL’s on the client. If the client only has a single redirect URL configured, then this parameter is not mandatory. However, if there are multiple, then a return URL must be specified.
state	Recommended	A random string (typically 40 - 100 characters) which is included in the request and token response. Can be used by the client application to prevent CSRF attacks.
code_challenge_method	Required	The method used to hash the code verifier. Should use S256
code_challenge	Required	The hashed code verifier.

Successful auth response params

Param	Description
code	An authorisation code to be exchanged for the access token.
state	The string that was included in the request. This should be verified against the state value, stored prior to the request.

Token request params

Param	Type	Description
client_id	Required	The same OAuth Client ID from the request.
grant_type	Required	authorization_code
code	Required	The code from the auth request.
redirect_uri	Required	The same redirect URI from the request.
code_verifier	Required	The plaintext code_verifier used to generate the code_challenge.

Successful token response params

Param	Description
access_token	The requested access token.
token_type	Bearer
expires_in	Token expiry time in seconds.
refresh_token	A refresh token. Can be used for to access the resource again when the current token expires.

Refresh Token

Description

When the current token has expired, the user can use the previously acquired refresh_token to request a new one. This is done by passing the refresh_token back to the token endpoint but using the refresh_token grant flow.

Token request params

Param	Type	Description
client_id	Required	The OAuth Client ID used to request the initial token.
client_secret	Required (unless PKCE)	The Secret of the OAuth Client. Not needed if initial request was with PKCE.
grant_type	Required	refresh_token
refresh_token	Required	The refresh_token from the initial auth request.

Successful token response params

Param	Description
access_token	The requested access token.
token_type	Bearer
expires_in	Token expiry time in seconds.
refresh_token	A refresh token. Can be used for to access the resource again when the current token expires.

Implicit

Description

The implicit flow is intended for user-agent-based clients (e.g. single-page apps) that can’t keep a client secret because all of the application code is easily accessible.

The client application requests an access token from the authorization server via a redirect to the authorize endpoint, including the client ID and redirect URL as query parameters. If the user provides consent, the authorization server issues an access token in the redirect URL fragment.

Auth request params

Param	Type	Description
client_id	Required	The ID of the OAuth Client
response_type	Required	token
redirect_uri	Recommended	The redirect URL of the app, where auth responses will be sent. The URL must match one of the configured return URL’s on the client. If the client only has a single redirect URL configured, then this parameter is not mandatory. However, if there are multiple, then a return URL must be specified.
state	Recommended	A random string (typically 40 - 100 characters) which is included in the request and token response. Can be used by the client application to prevent CSRF attacks.

Successful auth response params

Param	Description
access_token	The requested access token.
token_type	Bearer
expires_in	Token expiry time in seconds.