How to connect to an API

[#1]

• Getting started
• Choose an API product
• Create an account
• Getting an application
• Authentication
• Secured OAuth2 flow with client private key
• An authorized API request
• Authentication Error Response
• HTTPs support
• Request header & responses
• Request headers
• Response codes

Getting started

Choose an API product

Go to the API Library page and select an API.

The status of an API is displayed using the following labels:

• General: the API is available in production.
• Controlled: the API is available for a limited amount of users.
• Deprecated: the API is being phased out. We do not accept any new connections.
• Concept: the API is currently under development, but you are welcome to take a look.

If you plan to use an API in production, view the API requirements for that API, and ensure that you comply. If you would like to know more about the different statuses of an API please go here.

Create an account

To use a YouServe API product, you must register and create an account. An account is quick to set up and is free of charge. You only need your phone and company address to register.

To register and create an account:

• 1. Click Create an account.
• 2. Enter your details. (Please register with your company email).
• 3. You will receive an SMS on your mobile to confirm.

Getting an application

After login, you can go to Your Apps and see all applications you have access to.

Creating applications on the developer portal is done at this moment with a ticket through support. Please go to the support section for details.

As soon as the request is processed the application will show up in the developer portal.

Authentication

We follow current industry standards and best practices. Authentication/authorization is no exception. As part of the Identity and Access Management Strategy for system-to-system integrations, our APIs are based on OAuth 2.0 and the authorization grant Client Credentials.

Every API consumer system will be provisioned in our Developer portal as a Client Application (App). API key (client_id) and Secret Key (client_secret) will be provided to be used by Apps as credentials.

Apps will be able to authenticate and get an access token (JWT) within the response payload. Subsequent request authorization will be based on that access token previously retrieved.

Get the access token

In order to grant access to a target API, Apps must first authenticate against our Authorization Server. The request payload must include the Content-Type header and the HTTP body must include the required Client Credentials (API Key and Secret Key).

curl -X POST 
 https://api.youserve.nl/authentication/token 
 -H 'Cache-Control: no-cache' 
 -H 'Content-Type: application/x-www-form-urlencoded' 
 -d 'client_secret={client_secret}&client_id={client_id}&grant_type=client_credentials'

Below, is a response payload example containing the access token and the expiration time which is 60 min. After that time Apps need to re-authenticate to get a new access token.

{
  "access_token": "eyJraWQiOiJCSVpTR1dfSU5URVJOQUxfSURQIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
  "token_type": "Bearer",
  "expires_in": "7199"
}

 

Secured OAuth2 flow with client private key

This is an additional security level to retrieve the access token. Instead of using API key (client_id) and Secret Key (client_secret), the token will be retrieved using the API Key (client_id) + client_assertion (generated with a private key).

Get the access token

In order to grant access to a target API, Apps must first authenticate against our Authorization Server. The request payload must include the Content-Type header and the HTTP body must include the required Client Credentials (API Key and client JWT).

curl --location --request POST 'https://api.youserve.nl/sec/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_assertion={client_jwt}' \
--data-urlencode 'grant_type=client_credentials'

The value of the client_id parameter is the API Key of the application created by the customer in the Dev Portal, and the value of the client_assertion parameter is the client JWT. 

Below, is a response payload example containing the access token and the expiration time which is 60 min. After that time Apps need to re-authenticate to get a new access token.

{
  "access_token": "eyJraWQiOiJCSVpTR1dfSU5URVJOQUxfSURQIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ...",
  "token_type": "Bearer",
  "expires_in": "7199"
}

Client JWT

To set up the connection a private and public key need to be generated. The public key needs to be sent to Visma YouServe, to be registered. 

The private key should be used in the generation of the client JWT.

Example of the header section of JWT:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "c812sdf3468kjk0348sgsfg102398ee"
}

Example of the payload section of JWT:

{
  "sub": "{api_key}",
  "iss": "client.yourdomain.com",
  "exp": 1646832954,
  "iat": 1646832054,
  "jti": "b3953f18-4126-4378-8299-d4a0e6355140"
}

Some useful tips:

• kid; (header section), the element kid should be included and its value must be the key id of the public key provided to Visma YouServe
• sub; In the Payload section, we only require the claim "sub" which must contain the client_id (API key in developer portal)
• exp; be advised not to use local time or specific timezone to generate the value of exp claim, it should be specified in UTC. According to RFC 7519,  the value of this claim identifies the expiration time on or after which the JWT must not be accepted for processing. The proper value for this is a client decision but considering the purpose of the JWT, 10 minutes after the JWT is created is sufficient.
• iat; the value of the iat claim should be the time at which the JWT was issued. This is an optional claim and the details are explained here 

An authorized API request

After the Apps have received a valid token, they are ready to perform requests to any of our YouServe APIs. Apps must use the Authorization header containing the access token. In addition, will need to mark every request with the Client ID, using a custom header for that purpose.

Below, is a fetching data request example:

curl -X GET 
 'https://api.youserve.nl/requests/v1.0/expensesRequests/' 
 -H 'Cache-Control: no-cache' 
 -H 'Authorization: Bearer eyJraWQiOiJCSVpTR1dfSU5URVJOQUxfSURQIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhcHAiOiJ7XCJpZFwiOlwiMjBhZjIwNzUtMmM0ZS00ODdjLTliYzAtNDFmMDU2NWU5NGJkXCIsXCJuYW1lXCI6XCJnbTUtaW50ZXJuYWwtYXV0aC1wcm92aXNp...' 
 -H 'X-Client-Id: {client_id}'

Authentication Error Response

The error payload shown below describes the 401 error response Apps will receive in case of any authentication error.

{
 'message': 'Authentication Error',
 'correlationId': 'rrt-0d027480041e2a148-a-de-7885-572449-1',
 'issuedAt': '2018-03-27T07:44:25.554Z',
 'errorCode': 'unauthorized',
 'statusCode': 401
}

Miss use reasons for having authentication errors are:

• Wrong credentials

• Expired credentials

• Unauthorized access tokens

  • Invalid

  • Expired

HTTPs support

Our API's domain is secured by using DigiCert (SHA2) certificates, a worldwide industry-recognized provider.

ProtocolKey exchangeCipher

TLS 1.2 (only)

ECDHE RSA with X25519

AES_256_GCM

All HTTP requests will be refused with a Not Found 404 error response.

Request header & responses

Request headers

Our APIs have headers in common

Header NameDescription

Cache-Control	The Cache-Control general-header field is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain. In our authentication request, the header is mandatory with the value Cach-Control: no-cache
Content-Type	The content type of the resource in case the request requires content in the body. Example: Content-Type: application/x-www-form-urlencoded
Authorization	The information required to request authentication
Accept	The Accept request-header field can be used to specify certain media types which are acceptable for the response. Example: Accept: text/plain
X-raet-tenant-id	This header is used to specify for which tenant the data is requested. For tokens with single-tenant access, this header is not mandatory x-raet-tenant-id: 1234567

Response codes

Our APIs have response codes in common.

TypeResponsesSituation

Success Codes	200 OK	Synchronous read, update, and delete operations
201 Created	Synchronous create requests
202 Accepted	A-synchronous operations
204 No Content	Referring to non-existing entity (e.g. after delete)
Redirection Codes	304 Not Modified	Resource has not been modified.
308 Permanent redirect	Resource has permanently moved.
Invalid Request Errors	400 Bad request	Bad Request (e.g. validation errors)
401 Unauthorized	Not Authorized: Missing or invalid access token
403 Forbidden	Not Authorized: Authenticated, but user has no access to the API
404 Not Found	Invalid  URL: Item does not exist (anymore). The canonical identifier (collection/{canonical id}) cannot be found. Not Authorized:  Authenticated, access to API, but user has no access to the resource (data authorization).  From a security standpoint, we don't expose the reason why the object could not be found because an attacker can use this to figure out the internals of our system.
409 Conflict	Concurrency problem: Record changed by another user
Server Errors	500 Internal server error	Server Error (e.g. database failure, event could not be sent)
503 Service unavailable	Server Error (resource temporary not available)