How to connect to an API

[#1]

Choose an API product

Youforce has several API products available, you find more information here: 

https://developer.visma.com/api/youforce

Every API covers a different use cases, for example

• The IAM API is intended for identity & access management systems and enables the provisioning of users in other systems like Active Directory or IDP. 
• The Learning API provides employee data that is relevant for applications in the learning, development, appraisal domain, etc.  
• The File API allows you to download or upload files directly from Youforce.

In this way we help to achieve ‘purpose binding’ required to safeguard the privacy of employees and to comply with GDPR legislation. It furthermore allows us to tailor and grow the API supporting specific needs in that domain

Create an account and application
To use an Youforce API product, you must register and create an account. An account is quick to set up and is free of charge. A step by step manual is availible here.

Get the access token

In order to grant access to a target API, Apps must first authenticate against our Authorization Server. 

This token will provide access to a particular tenant in a specific application. Hence, this step will require knowing the client-id, client-secret and tenant-id.

curl -X POST 

 'https://connect.visma.com/connect/token'

 -H 'Cache-Control: no-cache' 

 -H 'Content-Type: application/x-www-form-urlencoded' 

 -d 'client_secret=xxxxxxx

     &client_id=xxxxxxxx

     &tenant_id=xxxxxxxx

     &grant_type=client_credentials'

Below, a response example containing the access token, the authorized scopes and the expiration time which is 1 hour max. After that time Apps need to re-authenticate to get a new access token.

{

    'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',

    'expires_in': '3600',

    'token_type': 'Bearer',

    "scope": "youforce-fileapi:files:list youforce-fileapi:files:upload"

}

HTTPs support

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

Protocol	TLS 1.2 (only)
Key exchange	ECDHE RSA with X25519
Cipher	AES_256_GCM

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

Request headers

Our APIs have headers in common

Header Name	Description
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 content in the body. Example: Content-Type: application/x-www-form-urlencoded
Authorization	The information required for 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

Response Codes

Our APIs have response codes in common.

Type	Responses	Situation
Succes 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 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 send)
503 Service unavailable	Server Error (resource temporary not available)