Standard authentication

Completing standard authentication

To make a request to our Business API, you’ll first need to get an access_token by following the standard authentication process shown below.

1. Get a {client_id} and {client_secret}. These will be issued when setting up the API, and act as a username and password for your application.
2. Make a POST request to https://api.soldo.com/oauth/authorize with your {client_id} and {client_secret} as body parameters, and set the Content-Type as application/x-www-form-urlencoded.
3. Get the access_token value of the JSON response. You'll need to include this token preceded by "Bearer " in all requests sent to our resource server as part of the Authorization header. Below you can find an example showing how the access_token can be used as part of a request:

curl --request GET \
   --url https://api.soldo.com/business/v2/employees \
   --header 'accept: application/json' \
   --header 'authorization: Bearer {access_token}'

⚠️

Expiration

Every access_token expires after 7200 seconds (2 hours), so you'll need to keep this in mind when designing your application. In order to avoid overloading your system and Soldo's, we recommend requesting a new access_token:

• once 2 hours have elapsed since the previous authentication. You'll need to keep track of the authentication time for this.
• after the old token has expired and the 401 Unauthorized error is returned, meaning new authentication is required.

Let's look at an example

The example below shows how to obtain an access_token with the Client ID and Client secret issued when setting up the API:

# To authenticate, use:

curl --request POST \
     --url https://api.soldo.com/oauth/authorize \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data 'client_id={client_id}&client_secret={client_secret}'

# The above command returns a JSON structured as follows:

{
  "refresh_token": "{refresh_token}",
  "token_type": "bearer",
  "access_token": "{access_token}",
  "expires_in": "7200"
}

⚠️

Remember

You'll need to replace {client_id} and {client_secret} with the API credentials you generated when setting up the API.

Potential errors

Depending on the scenario, there are different types of errors that could occur during the standard authentication process. These include:

Invalid credentials (UNAUTHORIZED)

# HTTP Status code: 401 Unauthorized

{
    "error_code": "UNAUTHORIZED",
    "message": "user not authorized"
}

If you try to authenticate with an invalid client_id or client_secret, the server will return a 401 HTTP status with the error code UNAUTHORIZED.

To troubleshoot this error, try:

• making sure the request is formatted correctly by comparing it with the example above. You should check the method (POST), the URL (https://api.soldo.com/oauth/authorize), the body parameters (client_id={client_id}&client_secret={client_secret}), and the Content-Type header (Content-Type: application/x-www-form-urlencoded).
• verifying you're using the correct client_id and client_secret, and that the corresponding application is active on your Soldo web app. If you're not sure, you can regenerate your credentials or create a new application from scratch. Click here to learn more about this process.

Invalid access token (invalid_token)

# HTTP Status code: 401 Unauthorized

{  
    "error": "invalid_token",  
    "error_description": "The access token is invalid or has expired"  
}

If you make a request with an invalid or expired access_token, the server will return a 401 HTTP status with the error code invalid_token.

To troubleshoot this error, try:

• checking the access_token you're using is valid. If you're not sure, you can generate a new one by sending an authentication request to our server. Remember every access_token expires after 7200 seconds (2 hours).
• make sure the request is formatted correctly by comparing it with our API reference documentation. The access_token must be included in the Authorization header of all requests sent to our resource server. The access_token must be preceded by "Bearer ". Below you can find an example showing how the access_token can be used as part of a request:
  cURL

  curl --request GET \
     --url https://api.soldo.com/business/v2/employees \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {access_token}'