API Authorization

Authorization Guidelines

IPXO uses OAuth2 as the authorization mechanism. To use any of the provided APIs, you must have a valid access token.
To retrieve the token, you first have to create an App Key in the IPXO portal, for the tenant/company you wish to access. Please find how to create an APP in IPXO Portal.
Credentials are limited to single company. If you have multiple companies, you will have to create separate App Keys for each of them.

After App Key creation, you receive client_id and client_secret. You then use these with the client_credentials OAuth2 flow to authenticate and receive an access token.

The OAuth2 token endpoint is https://hydra.ipxo.com/oauth2/token

OAuth2 scopes are mapped to the separate APIs - e.g. if you wish to call the billing and dns apis, add billing dns to the scope parameter (simple string, values separated by spaces) in the token request.

Note

For now, all app keys have full permissions on the company, just like a user with an "owner" role. We will introduce more granular control for this in the future

Request

You can either use any of the various libraries available for this or a simple http request using curl, for example:

BASH

curl 'https://hydra.ipxo.com/oauth2/token' \
-X POST \
-d 'grant_type=client_credentials' \
-d 'client_id=__YOUR_CLIENT_ID__' \
-d 'client_secret=__YOUR_CLIENT_SECRET__' \
-d 'scope=billing'

Response

JSON

{
"access_token": "2FaCiq7RfkyfdY7ngMyR3QfkDvvVRIwdIqJJpoOi1SQ.H2puQPlAQiGsoVEBEb06WuMOpvDkQQicwOKCjAJPSk4",
"expires_in": 86399,
"scope": "billing",
"token_type": "bearer"
}

Now you can use the access_token to call the actual APIs.
The token will be active for the duration of expires_in (in seconds), and only for the APIs specified in the scope.

Note

While you can request a new token for every operation, it is advisable to implement token caching on your side.

To call any API, simply add Authorization: Bearer <access_token_value> header to your request.
For example, to list the invoices for the tenant

Request

BASH

curl 'https://apigw.ipxo.com/billing/v1/<your_tenant_uuid>/invoices' \
-H 'Authorization: Bearer 2FaCiq7RfkyfdY7ngMyR3QfkDvvVRIwdIqJJpoOi1SQ.H2puQPlAQiGsoVEBEb06WuMOpvDkQQicwOKCjAJPSk4'