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 The access token endpoint is This should be all you need to configure your client.

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


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 with these query parameters:

response_typestringMust be set to code
client_idstringYour client/application ID
scopestringA space-delimited string of scopes to request. Read more
redirect_uristringThe URI we will redirect the user back to your app with (must be a registered URI with your application)
statestringAn optional state string to prevent CSRF attacks on your application


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:

  • - access the user's details and preferences
  • user.write - access to change the user's details and preferences
  • - access to list and view transaction accounts
  • accounts.write - access to update and delete transaction accounts
  • - access to list and view accounts and transactions
  • transactions.write - access to create, update and delete transactions
  • - 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 with these fields:

grant_typestringMust be authorization_code
client_idstringYour client/application ID
client_secretstringYour client/application secret
redirect_uristringThe same redirect URI for your application used in the authorization step
codestringThe 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 with the following fields:

grant_typestringMust be refresh_token
client_idstringYour client/application ID
client_secretstringYour client/application secret
refresh_tokenstringThe refresh token
scopestringOptional 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, and transaction.write scopes and no longer require the transaction.write scope, you could provide user.basic 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. 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.