The PocketSmith API uses the OAuth 2 standard for authorisation. This allows users to delegate third parties discrete access to their PocketSmith account. This guide walks through the auth code flow for a third party to request and obtain access to a PocketSmith user's account. It's recommended that you have a reasonable understanding of OAuth 2 concepts before you continue - Aaron Parecki's OAuth 2 Simplified could be a good place to start.

Client credentials

Before you can use OAuth, you must register your application with PocketSmith and obtain your client_id and client_secret. These are used to identify your application when making requests to the OAuth API endpoints. Get in touch to tell us about your app and get your credentials.

Existing third-party clients

OAuth is pretty involved, so it would make sense to use an existing OAuth 2 client for your language if possible to save time. Here are a few examples:

The authorisation URL is https://my.pocketsmith.com/oauth/authorize. The access token endpoint is https://api.pocketsmith.com/v2/oauth/access_token. This should be all you need to configure your client.

Read on to roll your own if none of those suit your needs.

Authorization

The authorization code flow starts off by redirecting the user to a PocketSmith-hosted page which asks them if they want to allow your app the requested access to their account. The URL you need to send the user to is https://my.pocketsmith.com/oauth/authorize with these query parameters:

Field	Type	Description
response_type	string	Must be set to `code`
client_id	string	Your client/application ID
scope	string	A space-delimited string of scopes to request. Read more
redirect_uri	string	The URI we will redirect the user back to your app with (must be a registered URI with your application)
state	string	An optional state string to prevent CSRF attacks on your application

Scopes

All PocketSmith API endpoints are under a scope. For example, to list a user's transactions, the access token you use must have been granted access to the transactions scope. When requesting access to a user's account, you must specify a list of scopes you want (i.e. which parts of their account you want to access).

Scopes available for public use are:

user.read - access the user's details and preferences
user.write - access to change the user's details and preferences
accounts.read - access to list and view transaction accounts
accounts.write - access to update and delete transaction accounts
transactions.read - access to list and view accounts and transactions
transactions.write - access to create, update and delete transactions
categories.read - access to view categories
categories.write - access to edit and delete categories
budget - access to analyse budgets and trends

If you are requesting scopes that the user has already approved for your app, the user won't be prompted again to approve or deny and will instead be redirected back straight away.

Handle the returning user

Regardless of if the user approves or denies access, they will be returned to your application on the redirect URI you provided. If access was approved, the URI will have a code parameter which your server-side application can use to obtain an access token. If access was denied, the URI will have an error parameter with the value access_denied.

Obtain an access token

Once you have the authorization code from the returning user, you can make a request to the OAuth API to exchange it for an access token, which can be used to make API calls. Make a POST request to https://api.pocketsmith.com/v2/oauth/access_token with these fields:

Field	Type	Description
grant_type	string	Must be `authorization_code`
client_id	string	Your client/application ID
client_secret	string	Your client/application secret
redirect_uri	string	The same redirect URI for your application used in the authorization step
code	string	The authorization code the user returned to your application with

If successful, you will be issued with an access token for making API calls. This should be provided as a header: Authorization: Bearer [token].

Refreshing the access token

Access tokens themselves have a lifetime of 1 hour (3600 seconds). After that time has elapsed, the access token must be refreshed. When you were originally issued your access token, there was an accompanying refresh_token. This is used with the refresh_token grant type to get yourself a new access token and refresh token pair. This exists for security purposes, so that if an access token is stolen, there is only a limited window of opportunity for it to be abused. Your client_id and client_secret are required for the refresh process, which should be kept safe.

To refresh your access token, make a POST request to https://api.pocketsmith.com/v2/oauth/access_token with the following fields:

Field	Type	Description
grant_type	string	Must be `refresh_token`
client_id	string	Your client/application ID
client_secret	string	Your client/application secret
refresh_token	string	The refresh token
scope	string	Optional list of space-delimited scopes. Used for de-escalating the scope for the new access token. For example, if you initially requsted the user.basic, transactions.read and transaction.write scopes and no longer require the transaction.write scope, you could provide `user.basic transaction.read` as the scope field so your new access token will no longer have access to the transaction.write scope. You can also escalate scope, but only scopes originally approved by the user can be included.

Implicit flow

The above auth code flow is suitable for applications that have a backend, such that they are capable of keeping their client_id and client_secret private. However, there are a class of applications that are incapable of keeping these secrets -- for example, JavaScript apps running in the browser (e.g. AngularJS).

For these use cases, we implement a simpler and cut-down version of the auth code flow. You still redirect the user to PocketSmith for authorisation, but instead of using response_type=code, you should use response_type=token. Then, instead of the user being redirected back with a code in the query string, they'll be redirected back with the access token itself right away, e.g. https://your.app/callback#access_token=0ab61721b9a...&expires_in=3600&token_type=Bearer. The access_token can be used right away to make API calls.

Note that a refresh token is not provided for the implicit flow, as using a refresh token securely requires client authentication with your client_id and client_secret, which are not safe to keep in a client side application. You will need to redirect the user to PocketSmith for authorisation again once the token has expired. If the user is still logged in to PocketSmith, they'll be redirected straight back seamlessly.