Authentication

Authentication resource is used for saving the access tokens to third party services to which certain tasks should be done. The resource is identified through its id field, and in addition is defined by the provider, access_token, refresh_token and expires_at field. A new resource is created through a POST request, when the user has to go through with the login procedure in order for the Scheduler BB to obtain a valid access token. The resulting access_token is used whenever a task that uses a ${provider_access_token} escape sequence.

Expired tokens are automatically refreshed, while the logout procedure can be done through a DELETE request to Scheduler BB.

Scheme:

{
  "id": "UUID",
  "provider": "String",
  "access_token": "String",
  "refresh_token": "String",
  "expires_at": "Integer",
  "active": "Boolean"
}

Example:

{
  "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "provider": "f4w",
  "access_token": "9f7f6cdc-c79c-11e6-9d9d-cec0c932ce01",
  "refresh_token": "730b4221-86c6-4e3f-839e-ff1e859b3300",
  "expires_at": 1482338754,
  "active": true
}

GET methods

GET /api/v1/authentications

Returns all authentications with their relative information if at least one resource exists, otherwise returns an empty collection.

Example request:

GET /api/v1/authentications HTTP/1.1
Host: https://scheduler.hid.facts4.work

Example response:

HTTP/1.1 200 OK
Content-type: application/json

[
  {
    "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
    "provider": "f4w",
    "access_token": "9f7f6cdc-c79c-11e6-9d9d-cec0c932ce01",
    "refresh_token": "730b4221-86c6-4e3f-839e-ff1e859b3300",
    "expires_at": 1482338754,
    "active": true
  }
]
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Response JSON Array of Objects:
 
  • id (string) – id of the authentication
  • provider (string) – string identifier of the provider used
  • access_token (string) – access token obtained from the provider
  • refresh_token (string) – refresh token obtained from the provider
  • expires_at (integer) – UNIX timestamp of expiry date of access token
  • active (boolean) – should this Authentication be used, automatically invalidated when refresh fails
Status Codes:

POST methods

POST /api/v1/authentications

Adds a new authentication. You will have to provide username and password to generate a valid authentication for the f4w OAuth provider. f4w is currently the only OAuth2 provider supported. Returns the new resource or error message.

Example request:

POST /api/v1/authentications HTTP/1.1
Host: https://scheduler.hid.facts4.work
Content-Type: application/json

{
  "provider": "f4w",
  "username": "real_user",
  "password": "secret_password"
}

Example response:

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "986c6f2e-7c49-4c0b-9bb3-9566ea3e9b02",
  "provider": "f4w",
  "access_token": "9f7f6cdc-c79c-11e6-9d9d-cec0c932ce01",
  "refresh_token": "730b4221-86c6-4e3f-839e-ff1e859b3300",
  "expires_at": 1482338754,
  "active": true
}
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Request JSON Object:
 
  • provider (string) – string identifier of the provider used
  • username (string) – username of current provider
  • password (string) – password of current provider
Response JSON Object:
 
  • id (string) – id of the authentication
  • provider (string) – string identifier of the provider used
  • access_token (string) – access token obtained from the provider
  • refresh_token (string) – refresh token obtained from the provider
  • expires_at (integer) – UNIX timestamp of expiry date of access token
  • active (boolean) – should this Authentication be used, automatically invalidated when refresh fails
Status Codes:

DELETE methods

DELETE /api/v1/authentications/:id

Delete an existing authentication, responds with the confirmation or error. Can only delete one resource at a time, to remove a collection of machines call the DELETE method for each element.

Example request:

DELETE /api/v1/authentication/ae54af76-964f-4ed8-8700-793b2ed5c20b HTTP/1.1
Host: https://scheduler.hid.facts4.work

Example response:

HTTP/1.1 200 OK
Parameters:
  • id (string) – authentication’s unique id
Query Parameters:
 
  • access_token (string) – valid access token for OAuth2 authentication
Status Codes: