How do I... Authenticate with Oneserve APIs?

1. Glossary

Token - This token is not only proof that the user is authenticated, but it also contains metadata about the user. Things like the Oneserve customer they belong to, their username and a few other bits. Expires after 60 minutes

Refresh Token - This token can be used to get another Token without having to pass your password to us again. Expires after 30 days.

Bearer Authentication - The name “Bearer authentication” can be understood as “give access to the bearer of this token.”

2. Using the Oneserve APIs

How to fetch a Token

Call the login endpoint documented here (bear in mind, this is still v0) https://api-cans.oneserve.co.uk/v1/api-docs#/Authentication/login
1. The returned payload will contain a Token and a Refresh Token
After 60 minutes, to get a new valid token, you can:
1. Send the Refresh Token to the endpoint documented here https://api-cans.oneserve.co.uk/v1/api-docs#/Authentication/refresh
After 30 days, you’ll need to get a new Refresh token. Do that by repeating step

How to use a valid Token

To call any of our APIs, documented here https://api-cans.oneserve.co.uk/v1/api-docs#/
1. You must use an ‘Authorization’ header of ‘Bearer <token>’

3. Example Authentication

Example url: https://api-cans.oneserve.co.uk/v1/auth/login with a body like:

{
  "user": {
    "companyName": "Build-Name",
    "userName" : "first.lastname"
  },
  "password": "MyPassword"
}

User token includes the tenant name, which tells the app which db to look at.
Using the Auth guide generate an auth token and pass this with each call.
Not specific User Type needed, but type rights relevant to the API being called are required
GET appointments requires Appointment_Read for example.
New APIs use the new type rights and will adhere to client/team filtering configs

URLs must match build environment

Live: https://api-cans.oneserve.co.uk/v1/

Pre-Prod (Test): https://api-cans-preprod.oneserve.co.uk/v1/

v1 API