OAuth2 Flow

Overview of the flow OAuth2 Flow ReceiptHero
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
Scope
Description
receipt:write
Sending receipts to the ReceiptHero system
receipt:read
Reading receipts from the ReceiptHero system
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 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. 
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
Scope
Description
receipthero_id
Unique connection identifier (contained in the JWT token)
redirect_uri
The URI where the user is redirected after taking actions on the connection update view
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
​

Scope	Description
receipt:write	Sending receipts to the ReceiptHero system
receipt:read	Reading receipts from the ReceiptHero system

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 if provided)

Scope	Description
receipthero_id	Unique connection identifier (contained in the JWT token)
redirect_uri	The URI where the user is redirected after taking actions on the connection update view

Parameter	Description
status	Describes the user action. Possible values are 'cancelled', 'modified' and 'removed'
receipthero_id	Unique connection identifier

Last modified 1yr ago