How to obtain keys

To obtain an API key you first need to have an account (as an organization administrator) in a production or sandbox environment. When having this and being logged in to the system, you need to activate API connectivity on the Marketplace page. To manage API keys go to Users in the menu and click the API Key tab.

🚧

Long-lived access token

We support the creation of long lived access tokens, but we recommend you to use Oauth process as it will provide a more secure implementation.

OAuth 2.0 Authorization Framework

Our APIs use the OAuth 2.0 framework for authentication. To access all end-points you need an access token, which is obtained via our OAuth process. You need to fetch a client ID and client secret in the expense platform which can be exchanged for a token that is needed to access the APIs.

The client secret must be kept confidential. The API Key has only access to the organization scope, to grant a larger scope like Partner level and Client Application access please contact our support.

Getting an access token

The OAuth client credentials flow is used to exchange a pair of client credentials (client_id
and client_secret) for an access token, using the grant_type client_credentials.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded"
-d  "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" 
https://expense.findity.com/api/oauth/token/

The server replies with an access token, type, expiration time, and a refresh token.

{  
"access_token":"RsT5OjbzRn4k9zqMLgV3Ia...",  
"token_type": "Bearer",  
"expires_in":3600,  
"refresh_token": "9MXOgvKAvB+tUSdCtML9u..."  
}

This access token is then used on other endpoints to your liking. When the token expires
you request a new one either with client ID and secret or using the refresh token.

Refreshing an access token

To use the refresh token, make a POST request to the service’s token endpoint with
grant_type=refresh_token, and include the refresh token and the client ID. Note that a
refresh token can only be used once.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded"
-d  "grant_type=refresh_token&client_id=CLIENT_ID&refresh_token=REFRESH_TOKEN"
https://expense.findity.com/api/oauth/token/

The response will be a new access token, and a new refresh token, just like you received
when exchanging the client ID and secret for the initial access token.

User access token

If you are building a solution where you need to act as a specific user (employee), a normal use case is when you are building against our Expense API, this is how to go about that.

Send a request to the authorization grant endpoint with the id of the user (person id or ExternalSourceID)

curl --request POST \
     --url https://stage-expense.findity.com/api/oauth/authorization-grant \
     --header 'accept: application/json' \
     --header 'authorization: Bearer a0949e44f748c4f8d99d310d398e0d515ad7f604855cf038894b8131c86d256bb077a1c38a29fbc03db1f92a065bc4ae9d7b37953a9779fe038f3406ab3b9277' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data user_id=8ab28c3e6f8023c3016f8046be110002

The response is an authorization code.

{
    "code": "38f99b5944cf4e298405ca4efe655cc1"
}

Exchange the code for an access token for the user.

curl --request POST \
     --url https://stage-expense.findity.com/api/oauth/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=authorization_code \
     --data code=38f99b5944cf4e298405ca4efe655cc1