Authentication

Keeping you safe and secure

Purple gradient wave Purple wave used to give a visual break between the header and body of the page.

Summary

As we are dealing with sensitive employee data requests, you will need to provide authentication information along with the request. This is done by sending an API key associated secret (we'll just call it an API key from now on) in a special header along with the request.

Let's find out how to get up and running...

 

Generating an API Key

In order to generate an API key, you will need permission to access the Admin section of the Youmanage application.  If you do not have permission, please speak with your System Administrator who will update your user account as required.

Once logged in to your instance of Youmanage, head to the Admin section where you will find the API link under the Integration menu:

 

Api Key menu item

 

From here you will see a list of all the API keys you have generated and their current status, along with options to edit and revoke active keys or to view the details of keys that have already been revoked:

 

List of API keys

 

Clicking the plus ('+') icon on the top right will allow you to create a new API key and decide what information will be granted to clients that are using the key. For example, if you are wanting to create an integration that will add in new employees from another system then you can check the Write box for Employee and that key will only have access to update information in the system, it will not be able to read any data:

 

Creating an API key

 

Once you have decided on the necessary rights and have given your key a meaningful name, which will help you remember the purpose of the key, you can click on Create.

The system will now generate an associated secret for your API key that your application will use to access the API. This is the only time you will be able to view this key so make sure you take note of it and keep it safe. Do not store this in source control, send over insecure channels or make this available to anyone else. If you feel your secret has been compromised revoke access immediately.

 

Created API key and associated secret

 

With that said and done, you will now have all you need to start making requests to the API!

 

Sending Authenticated Requests

Once you have an API key generated you can send it via the Authorization header along with your requests to gain access to the API:

curl -iH "Authorization: ApiKey MjI6YWFhYWFhYWEtYmJiYi1jY2NjLWRkZGQtZWVlZWVlZWVlZWVl"  "https://api.youmanage.co.uk/"
HTTP/1.1 200 OK
Date: Thu, 15 Aug 2019 15:58:42 GMT

{
    ...
}

Now that you're able to send authenticated requests you can proceed to the next step which looks at managing entities or read further to troubleshoot any issues you may encounter.

 

Troubleshooting

Sometimes things don't always go to plan and if this is the case, the following sections detail the error responses that are returned by the API when authentication has failed.

 

Authentication Required

If when sending a request you receive an error stating that "Authentication is required" (YM0100), then the API key you supplied is invalid:

curl -iH "Authorization: ApiKey invalid" "https://api.youmanage.co.uk/"
HTTP/1.1 401 Unauthorized
Date: Mon, 19 Aug 2019 14:33:51 GMT

{
  "Error": {
    "Code": "YM0100",
    "Reference": "https://developer.youmanage.co.uk/api/errors/ym0100"
    "Message": "Authentication is required"
  }
}

First check that the API key you are attempting to use is still active and has not been revoked by your system administrator. If the API key is still active then it is likely that you have mistyped it when entering the Authorization header and we would suggest re-entering it and trying again.

If you do not have a safe copy of the key, we would strongly advise recreating the API key through the Youmanage application.

 

Access Denied

If when sending a request you receive an "Access denied" (YM0150) response it means that the API key that was supplied is valid but has not been granted the rights to access the action: 

curl -iH "Authorization: ApiKey <secret>" "https://api.youmanage.co.uk/Absences"
HTTP/1.1 404 Not Found
Date: Mon, 19 Aug 2019 14:37:10 GMT

{
  "Error": {
    "Code": "YM0150",
    "Reference": "https://developer.youmanage.co.uk/api/errors/ym0150"
    "Message": "Access denied"
  }
}

This will happen if you are attempting to either access information where the associated API key does not have read access to the specific data or create/update records where the API key does not have write access to the information. 

If you are getting this result check that the API key has been configured with the correct access rights within the Youmanage application.

Back to all guides