This article relates to our products Simple Sign-On and Surp4ss!


NOTE: Before you can do this, you will need an API service account. By default with our current (2019) portal, this service account will need to be created for you. Our new portal will not require this step, and will allow you to use our API via your existing portal accounts.

We will provide you with an Username & Password of an API service account.


Authenticating to our API


To authenticate with our API:

POST

{
     "username": "exampleusername@eu.iamcloud.net",
     "password": "examplepasswordxyz"
}


To: api.iamcloud.net/api/v3/authenticate

This will return this response.

The bearer token data is held within "Data", and contains both the access and refresh tokens. You can store these for repeat calls so you don't need to keep entering the username and password. 


Our API uses a standard bearer token model, which means the (short expiry) access token is used to authenticate, but if the access token provides a 401, the (longer expiry) refresh token can be used to request a new access token, and start the process again.

Once you have authenticated with our API, you will be able to call our API to trigger the OTP. 


Triggering the OTP


So let's say we want to send the one-time password (OTP) for the account a@corporate.com (the user's company account on your domain) to b@alternative.com (the user's personal email address). The body would look like this:

 

{
    "type": 100,
    "to": [{"email": "b@alternative.com", "label": "b"}],
    "parameters": [
        {"name": "%username%", "value": "a"},
        {"name": "%email%", "value": "a@corporate.com"},
        {"name": "%employeeid%", "value": "aid"},
        {"name": "%alt-email%", "value": "b@alternative.com"},
        {"name": "%otp%", "value": ""}
    ]
}


In this case b@alternative.com will receive the OTP email template with parameters from the "parameters" dictionary. They will then be able to continue with the one-time password flow, by clicking on the link in the email, to create/update their password for the a@corporate.com account. 


If you have any questions or need any help please contact us on support@iamcloud.com