Skip to main content

Authentication

Use OAuth 2.0 and the API-Key to authenticate with Proactis APIs

The Proactis APIs use the OAuth 2.0 standard and a fixed API-Key for authentication and authorization. In short, OAuth 2.0 requires you to obtain an access token which you will have to include in every subsequent request so the server can confirm your identity.

OAuth 2.0 defines various ways that users can authenticate, so-called application grant types. The Proactis APIs supports the Client Credentials grant type.

Client Credentials-flow​

OAuth 2.0 based on client credentials is a simplified flow designed for server-to-server authentication. Unlike other OAuth 2.0 flows that involve user interaction, the client credentials flow is used when the client application itself needs to access resources from the resource server (API) directly without acting on behalf of a specific user. This flow is commonly used for machine-to-machine communication and for granting permissions to non-user entities (e.g., backend services, daemons, or CLI applications) to access protected resources.

Client Registration​

The client application must be registered with the authorization server. During registration, the client receives a unique client identifier, a client secret and an API-key. These credentials are used to authenticate the client application when making requests to the authorization server.

For initial registration and to obtain OAuth 2.0 credentials, please contact Proactis support.

caution

Treat authentication credentials the same way you would treat your passwords or other sensitive credentials.

Access Token Request​

The client application initiates the OAuth flow by sending a POST request to the authorization server's token endpoint. The request includes the client credentials (client identifier and client secret) in the request header, along with the grant type set to client_credentials to indicate the use of the client credentials flow.

Request Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic dXNlcm5hbWUxMjM6dmVyeXNlY3JldHBhc3N3b3JkMTIz
Accept: */*
Cache-Control: no-cache
Host: apius.proactiscloud.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 29
Request Body
grant_type=client_credentials

Access Token Issuance​

The authorization server validates the client credentials and, if successful, issues an access token. The access token is a bearer token that serves as proof of the client's identity and permissions.

Response Headers
Date: Wed, 19 Jul 2023 09:52:39 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 1230
Connection: keep-alive
x-amzn-RequestId: b7bb85c4-dcda-4117-ae42-e28201ec2915
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
x-amz-cognito-request-id: 2af69730-7b87-4613-bd81-d6b2eba5c82f
x-amzn-Remapped-Connection: keep-alive
Set-Cookie: XSRF-TOKEN=a439a0d9-17ad-410e-8baa-c418f1b94865; Path=/; Secure; HttpOnly; SameSite=Lax
x-amz-apigw-id: ITjQIFi9LPEFYnw=
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
x-amzn-Remapped-Server: Server
Expires: 0
X-Content-Type-Options: nosniff
Pragma: no-cache
x-amzn-Remapped-Date: Wed, 19 Jul 2023 09:52:39 GMT
Response Body
{"access_token":"eyJraWQiOiJCREpFVW1lUmFmZ3hhQmFmVndJTDdVOXI0eFBJUTFod3ZiTnB0OWc1VkRFPSIsImFsZyI6IlJTMjU2In
0.eyJzdWIiOiIxMjM0NTY3ODkwYWJjZGVmZ2hpamtsbW5vcCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiaHR0cHM6XC9cL2Fwa
S5wcm9hY3Rpc2Nsb3VkLmNvbVwvb3JkZXJzIGh0dHBzOlwvXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL2ludm9pY2VzIGh0dHBzOlwvXC9h
cGkucHJvYWN0aXNjbG91ZC5jb21cL3JlY2VpcHRzIGh0dHBzOlwvXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL3N1cHBsaWVycyBodHRwczp
cL1wvYXBpLnByb2FjdGlzY2xvdWQuY29tXC9hY2NvdW50aW5nIGh0dHBzOlwvXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL2VpbnZvaWNpbm
ciLCJhdXRoX3RpbWUiOjE2ODk3NjAzNTksImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTIuYW1hem9uYXdzLmNvbVwvZ
XUtd2VzdC0yX1Q4ekVBTjJ1QyIsImV4cCI6MTY4OTc2Mzk1OSwiaWF0IjoxNjg5NzYwMzU5LCJ2ZXJzaW9uIjoyLCJqdGkiOiI4ZjQzZTIx
Zi00ZWQzLTQ3MDAtYjgxMC00MzliNGRjZjY0YzIiLCJjbGllbnRfaWQiOiIxMjM0NTY3ODkwYWJjZGVmZ2hpamtsbW5vcCJ9.cimmDpATTj
WnrpC2xaQ-j-QtVqr3ThqnCSGWoSwhZmpr3oMkrpzQQSD4CtDePltVQaB-z7wgA9ZcXxeMefbH0h1-YLCzHSou4jN3YAMJxidNpCpCLvRA-
Mt89XN-4xM2EeaBxlGbbQNr6QwTX4a881sv-PiFmtWMVlMwKMzHdjrCXj9U5zc6dS4byOPsCDdDbmvRXVl2lvFnGASaglw9fdTvR00-s-ig
128bbI3ibvS3fS3MwECCGbEipZrg4fWt-YyOU7HBCZ3Lg3RwQYh-103cL-W7fm0JeOSAffU6GmQGv7SlkHY4rR03_jXjVeqzl8L6VfnJrSI
UlxIy5Tx-bQ","expires_in":3600,"token_type":"Bearer"}

Accessing the Proactis API​

With the access token obtained, the client application can now access the protected Proactis API by including the access token and the API-key in the request header. The resource server validates the access token to ensure that the client is authorized to access the requested resources.

Request Headers
x-api-key: KjMjmbz64amH8FrABCdEfGhn3bS6e7L
Authorization: Bearer eyJraWQiOiJCREpFVW1lUmFmZ3hhQmFmVndJTDdVOXI0eFBJUTFod3ZiTnB0OWc1VkRFPSIsImFsZyI6IlJTM
jU2In0.eyJzdWIiOiIxMjM0NTY3ODkwYWJjZGVmZ2hpamtsbW5vcCIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiaHR0cHM6XC9c
L2FwaS5wcm9hY3Rpc2Nsb3VkLmNvbVwvb3JkZXJzIGh0dHBzOlwvXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL2ludm9pY2VzIGh0dHBzOlw
vXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL3JlY2VpcHRzIGh0dHBzOlwvXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL3N1cHBsaWVycyBodH
RwczpcL1wvYXBpLnByb2FjdGlzY2xvdWQuY29tXC9hY2NvdW50aW5nIGh0dHBzOlwvXC9hcGkucHJvYWN0aXNjbG91ZC5jb21cL2VpbnZva
WNpbmciLCJhdXRoX3RpbWUiOjE2ODk3NjAzNTksImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTIuYW1hem9uYXdzLmNv
bVwvZXUtd2VzdC0yX1Q4ekVBTjJ1QyIsImV4cCI6MTY4OTc2Mzk1OSwiaWF0IjoxNjg5NzYwMzU5LCJ2ZXJzaW9uIjoyLCJqdGkiOiI4ZjQ
zZTIxZi00ZWQzLTQ3MDAtYjgxMC00MzliNGRjZjY0YzIiLCJjbGllbnRfaWQiOiIxMjM0NTY3ODkwYWJjZGVmZ2hpamtsbW5vcCJ9.cimmD
pATTjWnrpC2xaQ-j-QtVqr3ThqnCSGWoSwhZmpr3oMkrpzQQSD4CtDePltVQaB-z7wgA9ZcXxeMefbH0h1-YLCzHSou4jN3YAMJxidNpCpC
LvRA-Mt89XN-4xM2EeaBxlGbbQNr6QwTX4a881sv-PiFmtWMVlMwKMzHdjrCXj9U5zc6dS4byOPsCDdDbmvRXVl2lvFnGASaglw9fdTvR00
-s-ig128bbI3ibvS3fS3MwECCGbEipZrg4fWt-YyOU7HBCZ3Lg3RwQYh-103cL-W7fm0JeOSAffU6GmQGv7SlkHY4rR03_jXjVeqzl8L6Vf
nJrSIUlxIy5Tx-bQ
Content-Type: application/xml
Accept: */*
Host: apius.proactiscloud.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 277
Request Body
<costCenter>
  <id>1001</id>
  <name>Warehouse</name>
  <description>Warehouse</description>
  <online>1</online>
  <erpId>1001</erpId>
</costCenter>

Token Expiration and Renewal​

Access tokens have a limited validity period, after which they expire. If the access token expires, the client application needs to request a new access token using the same client credentials.

Contents