Page tree
Skip to end of metadata
Go to start of metadata

In order to authenticate to the API, you must use HTTP Basic Authentication over HTTPS. Authentication can be by username and password, by API user or by API tokens.

Authentication using Username and Password

You should present a basic authentication username together with your password. Your authentication username is available via the control panel, but consists of your username (normally an email address), followed by a forward slash, followed by your customer UUID. 

For instance, a customer with customer UUID f11850ca-e25d-40b8-bcfa-a574f2595831 and email address user@example.com would authenticate using the username user@example.com/f11850ca-e25d-40b8-bcfa-a574f2595831

The user presented must be a member of the 'Everyone' group of the customer whose UUID you present for authentication.

Authentication using API User and Password

You can create API users in the control panel which are indefinitely (i.e. until revoked) permitted to access the API. They can have separate levels of security using the group and permissions systems, i.e. they act like separate users on the same customer account. In this case they use an authentication name which is the API User UUID, followed by a forward slash, followed by your customer UUID. 

For instance, an API key with UUID 7711946f-d78d-4693-9d87-3a993107b82e with customer UUID f11850ca-e25d-40b8-bcfa-a574f2595831 would authenticate using the username 7711946f-d78d-4693-9d87-3a993107b82e/f11850ca-e25d-40b8-bcfa-a574f2595831.

Authentication using API Tokens

You can create API tokens using the API itself (using either of the above two methods to authenticated). The token is purely a UUID, and normally lasts for a short amount of time, but may be set to renew when successful authentication is made. When authenticating using an API token, the caller has the credentials of the owner (i.e. the creator) of the token. Pass solely the token as the username.

For instance, an API  key with UUID 141b25e2-a864-40ec-9b2b-670038302d51 created by customer UUID f11850ca-e25d-40b8-bcfa-a574f2595831 and email address user@example.com would authenticate using the username 141b25e2-a864-40ec-9b2b-670038302d51.

 

Authentication to the Admin API

In order to authenticate to the Admin API, the customer UUID you present must be either:

  • A customer with Billing Entity administration rights, or
  • A customer with Master Billing Entity administration rights.

Authentication to the Customer API

There are no additional restrictions for authentication to the customer API

Authentication to the Customer API using Admin Credentials

In order to authenticate to the Admin API using administrative credentials, the username/customer UUID you present for authentication must be either:

  • A customer with Billing Entity administration rights, or
  • A customer with Master Billing Entity administration rights.

You should then present an additional SOAP header 'UsernameToken' (for the SOAP API), whose value should be set to the authentication username (the login username, a slash, and the customer UUID) of the user and customer that you wish to authenticate as. For the REST API the same can be done with an HTTP header of the same name.

For instance, if an admin user has a username admin@example.com and a customer UUID of 85017f72-8ca7-464a-8b7e-002c4b44a27a, it would pass admin@example.com/85017f72-8ca7-464a-8b7e-002c4b44a27a in the HTTP basic authentication, then to act as user user@example.com as above, it should add a header in REST of:

X-AssumeToken: admin@example.com/f11850ca-e25d-40b8-bcfa-a574f2595831

or in SOAP a Username token with value admin@example.com/f11850ca-e25d-40b8-bcfa-a574f2595831

The Open API

The Open API does not require credentials.

 

  • No labels