Overview
There are two means to authenticate with the SureCloud RESTful API
Session based authentication
This is primarily the means of testing or using the Swagger documentation’s "Try it out!" feature.
This requires the required user be signed on to SureCloud in the browser and the session cookie be passed with any requests in the header.
A user would authenticate/log in to SureCloud via the normal means https://secure.surecloud.com/ and then the API's can be called within the browser, or the session cookie can be extracted and used to make requests.
JSON Web Token (JWT) based authentication
The majority of the REST API services allow for a JWT to be passed with the request to authenticate the user.
A user will be issued a 'Secret Key', that can be used to request a JWT token. The key will identify the User and permissions available. Using the JWT will allow actions to be taken via the RESTful API in a secure and session free manner.
The following rules will apply:
- JWT authentication is limited to the RESTful API only.
- Users are assigned a 'Secret Key' by a 'Secret Key Administrator' within the Platform.
- A Token endpoint is provided in the RESTful API where users can request a JWT which
when granted will give them access for subsequent calls for a limited time (defaulted to one hour), Users will pass their email and secret key which is associated with the user in the Platform. - The JWT represents a user on the Platform.
- The JWT is digitally signed with a private key known only to the SureCloud Platform.
- The JWT is time limited (defaulted to 60 minutes).
- When a JWT has expired, a new token request must be made.
- The JWT use can be restricted by IP Address, IP Address Range and Hostname, Restrictions
will be associated with the user’s account on the Platform. - The JWT can be revoked at any time by a 'Secret Key Administrator'.
- The JWT are designed to expire at their time limit but can also expire during their existence via a few mechanisms within the Platform.
How Does it Work?
User requests a Token passing Secret Key and Email, the system identifies the User with these two pieces of information. If User is active, then a token is created which is associated with this user and it is set to expire after 60 minutes. The token is digitally signed with HMAC using SHA 512 before being returned to the user as the response. The user will inherit all the permissions they are granted on the Platform.
The User will then pass this JWT as a header e.g.
curl -X GET 'https://secure.surecloud.com/restful/v1/user'
--header 'Authorization: Bearer <JWTHere>'
--header 'Content-Type: text/plain'
Providing the User has the correct permissions to perform whatever the API call is attempting to do then it will succeed. Below is an example using some curl commands.
Curl Examples
Get Token, where secret key is ‘abc123’ and email is user1@surecloud.com
curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/plain'
--header 'X-client-secret: abc123' --header 'X-email: user1@surecloud.com'
'https://secure.us.surecloud.com/restful/v1/token'
Use the Token to retrieve a list of tasks where the token value is the value returned by the previous request:
curl -X GET 'https://secure.surecloud.com/restful/v1/tasks'
--header 'Authorization: Bearer <JWTHere>'
--header 'Content-Type: text/plain'
Manage Secret Key
Only Users who have been assigned a special role ‘Secret Key Administrator’ are capable of generating a Secret Key for a user.
If you wish to grant this role to a user within your organisation then please send an email requesting this to success@surecloud.com.
A Secret Key is a UUID value generated by the system, it is not exposed to the administrator. Users will be emailed a link which will then allow them to reveal their Secret Key.
If the key becomes lost or forgotten a new one must be requested from a Secret Key Administrator (i.e. the key is non-recoverable and the process must be repeated).
A secret key is added to an existing User by navigating to the Users list and expanding the columns 
, this should reveal a Secret Key column in the list, as below:
A 
in this column designates that a Secret Key currently does not exists for that User, whereas a 
icon represents a Secret Key is already associated with this User and can be revoked.
Adding a Secret Key
Use 
to add a Secret Key against the User you wish to add a key for, the following popup will be shown:
Click Ok to add the key for the User.
An email will be sent to the User from which it is possible to view the new Secret Key. The email will be formatted as follows:
Subject: SureCloud: Restful API Secret Key
Dear User 1,
A secret key has been generated so you can access our Restful API in a secure and headless manner.
Please use the following link to view your key. The link will be active for 7 days.
https://secure.surecloud.com/reveal.jsp?reveal=XYZAKQNEWQJJ!12353ASD
For guidance on how to use our Restful API, see https://secure.surecloud.com/swaggerDocumentation
Please keep your secret key safe at all times and do not allow others to use your account. If you believe
your secret key has been compromised, please notify SureCloud immediately by contacting support@surecloud.com or by opening a support ticket.
Please open a support ticket under the support tab for any queries.
Kind regards,
SureCloud
--
SureCloud Limited
https://www.surecloud.com
https://secure.surecloud.com
Upon revealing their Secret Key the link will invalidate, so cannot be used again. A new Secret Key must be requested if they wish to reveal the key for any reason again (it will be a new Secret Key).
The reveal link will be active for 7 days, then it will expire and a new link must be requested.
Restricting access
Once a key has been added the IP restrictions for this key can be managed by clicking the 
icon against the User in the Secret Key Column.
The following popup will be shown:
It is possible to specify a comma-separated list of IP Addresses, IP Ranges, CIDR and Hostnames. In the example above only if the User had a IP address of 127.0.0.1 would any token issued be valid.
The restrictions are applied at the point of attempting to use the token, not when the token is issued.
Any amendments to these restrictions become immediately effective for any existing active tokens or new
tokens issued after the change.
Revoking a Secret Key
Using the icon will revoke an existing Secret Key for the User it is against.
Click Ok to confirm.
Once Revoked a user will not be issued any new tokens with this key.
Any existing active tokens issued for this key will be immediately invalidated.
Request new reveal link
A Secret Key Administrator can request a new reveal link is emailed to a user by clicking the icon 
in
the Secret Key column for the user they wish to resent the email to.
Clicking OK will confirm and send the email.
Revealing a Secret Key
A user will receive an email which will enable them to reveal a secret key assigned to them.
This email will contain a link, when the user clicks on the link they will be redirected to the Reveal Secret page.
If the User currently authenticated is not the user that the key is intended for then the user will be informed they do not have the permissions to reveal this key e.g.
The user must login as the intended user so they can reveal their key.
If no user is logged in then they will be directed to the login page and once logged in the key will be
revealed e.g.
If the link has expired or has been previously revealed then the user will be informed, and must request a
new link from a Secret Key Administrator, e.g.
Comments