# OAuth2 Flow

Overview of the flow OAuth2 Flow ReceiptHero

![](/files/-ManaSmdfYXAzlAQqxcf)

## Get an authorization code

Initiate the flow by redirecting the user to the ReceiptHero consent page.

**Redirect**

```
https://dev.receipthero.io/auth?response_type=code&client_id={CLIENT_ID_HERE}&redirect_uri=https%3A%2F%2Freceipthero.io%2Fcallback&scope=receipt%3Awrite&state=cmVjZWlwdGhlcm9yb2Nrcw==
```

If the user approves the request then the authorization server will redirect the user to the redirect URI defined in the request.

**Scopes**

<table><thead><tr><th width="197.75639713408395">Scope</th><th>Description</th></tr></thead><tbody><tr><td>receipt:write</td><td>Sending receipts to the ReceiptHero system</td></tr><tr><td>receipt:read</td><td>Reading receipts from the ReceiptHero system</td></tr></tbody></table>

**State**

| Parameter         | Type   | Description                                                                                                                                                                  |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| message           | string | Custom message                                                                                                                                                               |
| partner\_metadata | object | Optional Partner defined key-value pairs for carrying relevant metadata (will be included in [webhook notification messages](/partner-app-api/notifications.md) if provided) |

To use the state parameters, the state is to be defined in JSON and encoded into Base64.

**Callback**

```
https://client-server.com/callback?code=1745ee387c3545b2b77bf37baaf3b3f5&state=cmVjZWlwdGhlcm9yb2Nrcw==
```

The client must make sure that the state matches the provided state value provided to the authorization endpoint. This protects against CSRF type of attacks. The code expires one minute after it has been created.

## Exchange the authorization code for an access token

The client sends the previously received authorization code to the token endpoint which then returns an access token.

**Request**

```
POST https://api.dev.receipthero.io/api/oauth/token

Content-Type: application/json

{
    "grant_type": "authorization_code",
    "code": "{CODE_HERE}",
    "client_id": "{CLIENT_ID_HERE}",
    "client_secret": "{CLIENT_SECRET_HERE}",
    "redirect_uri": "{REDIRECT_URI_HERE}"
}
```

The request can be made in either *application/json* or *application/x-www-form-urlencoded*.

**Response**

```
{
    "token_type": "Bearer",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWNlaXB0X2hlcm9faWQiOiI5Mjg5OTZmZC0yYTU3LTQ1NzctYjZlNy01ODNhZGM4ZGJlOGMiLCJpYXQiOjE2MjM3NDEwMDh9.gD17UFHxJoEmz_RrIHBQksjqgotyncoO8fDYurYPI2k"
}
```

The returned access token is a JSON Web Token.

In Token you get ID for this connection.&#x20;

**Claims**

| Claim           | Description       |
| --------------- | ----------------- |
| receipthero\_id | Unique identifier |

## Revoke Access Token

```
DELETE https://api.dev.receipthero.io/api/oauth/revoke
Host: api.dev.receipthero.io
Authorization: Bearer <USERS_OAUTH_TOKEN>
```

**Response OK**

```
HTTP 200 OK
Content-Type: application/json
```

**Response Not Found**

```
HTTP 404 Not Found
Content-Type: application/json
```

## **Update existing OAuth2 connection**

It is possible to update an existing OAuth2 connection by using this dedicated view.

```
https://dev.receipthero.io/membership?receipthero_id={receipthero_id}&redirect_uri={redirect_uri}
```

**Query Parameters**

<table><thead><tr><th width="208.13118706178528">Scope</th><th>Description</th></tr></thead><tbody><tr><td>receipthero_id</td><td>Unique connection identifier (contained in the JWT token)</td></tr><tr><td>redirect_uri</td><td>The URI where the user is redirected after taking actions on the connection update view</td></tr></tbody></table>

**Redirect**

The user is redirected back with the following query string parameters:

| Parameter       | Description                                                                          |
| --------------- | ------------------------------------------------------------------------------------ |
| status          | Describes the user action. Possible values are 'cancelled', 'modified' and 'removed' |
| receipthero\_id | Unique connection identifier                                                         |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.receipthero.io/partner-app-api/oauth-access.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.