Zoeken
Mijn Communities
Help

How to connect to an API

17-12-2021 08:53 (Bijgewerkt op 27-01-2022)
  • 0 Antwoorden
  • 0 kudos
  • 2616 Weergaven

 

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 an Youforce 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

The received token can be different based on the identity provider used

 

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 OAuth 2.0 and the authorization grant Client Credentials. Every API consumer system will be provisioned in our API Gateway as a Client Application (App). Client ID and Client Secret will be provided to be used by Apps as credentials. Thus, Apps will be able then to authenticate and get an access token (JWT) within the response payload. Subsequent requests authorization will be based on that access token previously retrieved.

 

flowdiagram.png

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.

curl -X POST 
 https://api.youforce.com/authentication/token 
 -H 'Cache-Control: no-cache' 
 -H 'Content-Type: application/x-www-form-urlencoded' 
 -d 'client_secret= iPWF123nlk2XYgUHV&client_id=qX0X S456YY4kJtDY5drCeZ0XT7nS5GxA&grant_type=client_credentials'

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

{
 'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
 eyJUaWNrZXRJZCI6IitMZWhGdVh3T0V2RTdtYk c4U3IyIiwiVXNlcklkIjoiSUMxMTI2NjYiLCJNZXN zYWdlSWQiOjAsIkNvbXBhbnlJZCI6NDAyODA 5MCwiRXhwaXJhdGlvbiI6NzIwMCwibmJmIjoiMTUyMjE zMzU5MTYwOSIsImV4cCI6IjE1MjIxMz M4OTE2MDkifQ.
 wSZGjncy4_CH98RIBdhTr9FsMtIIkVtV 3tkRoWvlrQQ',
 'token_type': 'BearerToken',
 'expires_in': '899',
}

An authorized API request

After the Apps has received a valid token, they are ready to perform requests to any of our Youforce 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, a fetching data request example:

curl -X GET 
 'https://api.youforce.com/requests/v1.0/expensesRequests/' 
 -H 'Cache-Control: no-cache' 
 -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
 eyJUaWNrZXRJZCI6IitMZWhGdVh3T0V2 RTdtYkc4U3IyIiwiVXNlcklkIjoiSUMxMTI2NjYiLCJNZXN zYWdlSWQiOjAsIkNvbXBhbnlJZCI6NDA yODA5MCwiRXhwaXJhdGlvbiI6NzIwMCwibmJmIjoiMTUyMjE zMzU5MTYwOSIsImV4cCI6IjE1MjIxMzM4OTE2MDkifQ.
 wSZGjncy4_CH98RIBdhTr9FsMtIIkVtV3tkRoWvlrQQ' 
 -H 'X-Client-Id: qX0XS456YY4kJtD Y5drCeZ0XT7nS5GxA'

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 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 header & responses

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

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.

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)

 

 

Labels:
0 Kudos
Medewerkers
Choose your region:
Choose your Region
Go