pwrd by

Get started with the Procurios API

These API's are accessible through OAuth2 using either the authorization code or the client credentials grant type. While it is not our intention to explain OAuth2 itself into detail, the following guides should help you get started. For more information on OAuth2 we recommend https://connect2id.com/learn/oauth-2.

There are two ways to connect with the Procurios API:

Authorization code

The authorization code grant type allows you as a client to use the Procurios API from the perspective of a user.

Procurios should have received:

  • A list of allowed redirect urls

You should have received:

  • An OAuth2 client id
  • An OAuth2 client secret
  • A token request endpoint url
  • A client authorization endpoint url
  • At least one scope to claim

The flow of calls should be:

  1. Direct the user to the authorization endpoint

    {clientAuthorizationEndPointUrl}?response_type=code&scope={space separated list of scopes}&client_id={clientId}&redirect_uri={redirectUrl}
    Example:
    https://procurios.com/l/oauth2/authorize?response_type=code&scope=profile&client_id=abc123&redirect_uri=example.com

  2. Receive the user with his or her access code

    {redirectUrl}?code={code}
    Example:
    https://example.com?code=X

  3. Call the token request endpoint with the access code and receive the access token

    POST {tokenRequestEndpointUrl} 
    Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id={clientId}&code={code}&client_secret={clientSecret}
    Example:
    POST https://procurios.com/l/oauth2/token 
    Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code&client_id=abc123&code=X&client_secret=dfe456

    Access token response:

    {'access_token': '{accessToken}'}
  4. Call the Procurios API with the header Authorization: Bearer accessToken
    (See below for examples)

Client credentials

The client credentials grant type allows you as a client to use the Procurios API from server to server without the context of a user. You should have:

  • An OAuth2 client id: {clientId}
  • An OAuth2 client secret: {clientSecret}
  • A token request endpoint url: https://api.craftbrouwers.nl/l/oauth2/token
  • At least one scope to claim: {space separated list of scopes}

Request an access token

Before you can make a call to an OAuth2 endpoint, you must first call the token request endpoint with the client id and secret to receive the access token.

POST https://api.craftbrouwers.nl/l/oauth2/token 

Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}&scope={space separated list of scopes}

The access token endpoint will reply with a response similar to this:


{
    "access_token": "{accessToken}",
    "token_type": "bearer",
    "expires_in": 3600,
    "scope": "null"
}

This access token is valid for a limited number of seconds, 3600 in the example above. For every subsequent API endpoint call, call the Transport-info API with the header: 

Authorization: Bearer {accessToken}

Call an (example) endpoint

Once you have your access token, example requests could look something like:

GET https://{tokenRequestDomain}/l/some_api/endpoint 
Accept: application/vnd.procurios.application+json; version=1
Authorization: Bearer {accessToken}
POST https://{tokenRequestDomain}/l/some_api/endpoint 
Accept: application/vnd.procurios.application+json; version=1
Authorization: Bearer {accessToken}

{
"key": "value",
"otherKey": 2
        }