# PayoutID OAuth2

PayoutID is Payout's OAuth2 and OpenID Connect provider. It supports three grants:

- [Authorization code grant](#authorization-code-grant): act on behalf of a user who approves access.
- [Refresh token grant](#refresh-token-grant): get a new access token without asking the user again.
- [Client credentials grant](#client-credentials-grant): call an API as your own client, without a user.

## Endpoints

| Endpoint | Sandbox | Production |
| --- | --- | --- |
| [Authorize user](https://developers.payout.tech/api/payout-id.html#authorization_redirect_for_user) | `https://id-sa.payout.one/oauth/authorize` | `https://id.payout.one/oauth/authorize` |
| [Retrieve token](https://developers.payout.tech/api/payout-id.html#endpoint_to_retrieve_authorization_token) | `https://id-sa.payout.one/oauth/token` | `https://id.payout.one/oauth/token` |

Payout registers your application as a PayoutID client and gives you a `client_id` and a `client_secret`. The client also holds your registered redirect URIs and the scopes you may request. Each API lists the scopes its endpoints require.

## Authorization code grant

Use this grant when you need data from a user or want to act on their behalf.

1. **Redirect the user.** Send the user's browser to [Authorize user](https://developers.payout.tech/api/payout-id.html#authorization_redirect_for_user) with your `client_id`, `response_type=code`, a registered `redirect_uri`, the `scope` you need and a `state` value.
2. **The user approves.** The user logs in or registers in PayoutID and approves the requested scopes.
3. **Receive the code.** PayoutID redirects the browser back to your `redirect_uri` with `code` and `state` in the query string. Check that `state` matches the value you sent. The code is valid for at most 60 seconds and works only once.
4. **Exchange the code for tokens.** Call [Retrieve token](https://developers.payout.tech/api/payout-id.html#endpoint_to_retrieve_authorization_token) with `grant_type=authorization_code`, the `code` and the same `redirect_uri`.
5. **Call the API.** Send the access token in the `Authorization: Bearer <access_token>` header.

![Authorization code flow sequence diagram](https://developers.payout.tech/_media/authorization_code_flow.png)

## Refresh token grant

Access tokens are short-lived: the lifetime is set per client, at most 24 hours, and `expires_in` in the token response tells you how long the token is valid. To keep access without sending the user through the flow again, use the refresh token issued with the access token from the authorization code grant. A refresh token is valid for at most 30 days.

A refresh token cannot be used to call an API. It can only be exchanged for a new access token: call [Retrieve token](https://developers.payout.tech/api/payout-id.html#endpoint_to_retrieve_authorization_token) with `grant_type=refresh_token` and the token in `refresh_token`.

## Client credentials grant

Use this grant to access resources of your own client, without a user's consent in Payout. Call [Retrieve token](https://developers.payout.tech/api/payout-id.html#endpoint_to_retrieve_authorization_token) with `grant_type=client_credentials`, your `client_id` and `client_secret`, and the `scope` you need. No authorization code is involved.

When a resource belongs to another provider, such as the user's bank, the user may still have to authenticate with that provider.