Making requests to the CloudLX API


Authorisation

The API uses OAuth2 access tokens to access all secure endpoints. Access tokens can be requested via the end point as detailed below.

As per OAuth2 standard, access tokens expire after 3600 seconds and can be re-requested using the issued refresh token. Refresh tokens expire after 604800 seconds (7 days) at which point a new access token will need to be generated using the client details.

Back to top

Permissions

The permissions of an access token will be based upon the client that requested the token. The access token is issued against a user account in the CloudLX portal. The API access permissions will mirror the permissions set for the user in the portal.

Back to top

API Versioning

You can request endpoints of the API specifying the Accept: header on your requests:

    Accept: application/vnd.cloudlx.v1+json

Versions will be released based upon the following criteria.

  • Making a breaking change to the semantics of an existing endpoint
  • Deprecating an existing endpoint
  • Authentication mechanism changes

Versions will NOT be increased in the following situations.

  • Additional fields added to the existing semantics
  • Additional endpoints created

Back to top

Obtaining an access token

Request

Endpoint: /api/oauth2/access-token
Method: POST
Headers: Accept: application/vnd.cloudlx.v1+json

Required Parameters

grant_type Description OAuth2 grant type - should always be client_credentials
Type String
Required Yes
Example client_credentials
client_id Description The client ID created in the CloudLX portal API Applications section
Type String
Required Yes
Example xYrKf2x3qWXm0Zn35l8ki5kRH22IP0RPmLR0TlLB
client_secret Description The client secret created in the CloudLX portal API Applications section
Type String
Required Yes
Example nykSBHIDynMHrwkGyXWzLFAXYbOVP3EKtk6pprOS

Response

Example:

                                
    {
        "access_token": "cxl784Nu0NNbsUhotFWNFOyC2noFs7ImlnEtNoCr",
        "token_type": "Bearer",
        "expires_in": 3600,
        "refresh_token": "PlaIgVUTpQpGKWgRqIXjfNn3GWQzkizPraHQLhGQ"
    }
                                
                            
access_token Description The access token to send in the Authorisation Bearer header
Type String
Example cxl784Nu0NNbsUhotFWNFOyC2noFs7ImlnEtNoCr
token_type Description The type of access token, will always be Bearer header
Type String
Example Bearer
expires_in Description The number of seconds until the access token expires and will need to be refreshed
Type Integer
Example 3600
refresh_token Description A refresh token that should be stored and used to request a new access token upon expiry
Type Integer
Example 604800

Back to top

Obtaining an access token from a refresh token

Request

Endpoint: /api/oauth2/refresh-token
Method: POST
Headers: Accept: application/vnd.cloudlx.v1+json

Required Parameters

refresh_token Description The refresh token obtained from a previous access token request
Type String
Required Yes
Example PlaIgVUTpQpGKWgRqIXjfNn3GWQzkizPraHQLhGQ
grant_type Description OAuth2 grant type - should always be refresh_token
Type String
Required Yes
Example refresh_token
client_id Description The client ID created in the CloudLX portal API Applications section
Type String
Required Yes
Example xYrKf2x3qWXm0Zn35l8ki5kRH22IP0RPmLR0TlLB
client_secret Description The client secret created in the CloudLX portal API Applications section
Type String
Required Yes
Example nykSBHIDynMHrwkGyXWzLFAXYbOVP3EKtk6pprOS

Response

Example:

                                
    {
        "access_token": "cxl784Nu0NNbsUhotFWNFOyC2noFs7ImlnEtNoCr",
        "token_type": "Bearer",
        "expires_in": 3600,
        "refresh_token": "PlaIgVUTpQpGKWgRqIXjfNn3GWQzkizPraHQLhGQ"
    }
                                
                            
access_token Description The access token to send in the Authorisation Bearer header
Type String
Example cxl784Nu0NNbsUhotFWNFOyC2noFs7ImlnEtNoCr
token_type Description The type of access token, will always be Bearer header
Type String
Example Bearer
expires_in Description The number of seconds until the access token expires and will need to be refreshed
Type Integer
Example 3600
refresh_token Description A refresh token that should be stored and used to request a new access token upon expiry
Type Integer
Example 604800

Back to top