Overview
--------
Imprest uses OAuth 2.0 Authorization Code flow to allow third-party apps to access accounting data on behalf of a user. Before you can make API calls, you need to:
1. Register an application in the Developer Portal to obtain a Client ID and Client Secret.
2. Direct the user to the Imprest authorization endpoint.
3. Exchange the authorization code for an access token.
4. Make API requests using the Bearer token.
Step 1: Register Your App
-------------------------
Go to My Apps → Create App and fill in:
- App name (shown to users during authorization)
- Redirect URI (where we send the user after authorization)
- Scopes (which data your app needs to access)
Step 2: Redirect the User
--------------------------
Send the user to:
GET /oauth/authorize
?client_id=YOUR_CLIENT_ID
&response_type=code
&redirect_uri=YOUR_REDIRECT_URI
&scope=money_in+money_out
&state=RANDOM_NONCE
The "state" parameter should be a random value you store in the session — we echo it back so you can verify the response is genuine.
Step 3: Exchange the Code
--------------------------
When the user approves, we redirect them to your redirect_uri with a "code" query parameter. Exchange it for tokens:
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
Response:
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 7200,
"scope": "money_in money_out"
}
Step 4: Make API Calls
-----------------------
Include the Bearer token in every request:
GET /api/v1/invoices
Authorization: Bearer ACCESS_TOKEN
X-Organization-Id: ORG_UUID
The X-Organization-Id header identifies which organization's data to access. The user's accessible organizations are returned from GET /api/v1/me/organizations.
Next Steps
----------
- Read the Authentication docs for refresh token flow and token revocation
- Check the Scopes reference to see available permissions
- See the API Reference for available endpoints