Authenticating

Working with authenticated endpoints in Suran API is a three-step process:

  1. Log in with a provision and PIN to start an authenticated session.
  2. Query the relevant endpoint(s) according to specified documentation.
  3. Log out to close the authenticated session. 

Before getting started, you will need to know which server hosts your data. Typically, this will be in the following format, with a variable number: hosting99.suran.com

 What if I don't know the hosting server?

You can find basic information about your provision (including 'host') with the following request:

# format
curl 'https://ferret.suran.com/getprovision?provisioncode={YOUR PROVISION CODE}'

# example
curl 'https://ferret.suran.com/getprovision?provisioncode=2524a545-58bc-426d-9802-f3cca41ebc8e'
BASH

Usage

All examples included below are for illustration purposes only and utilize mock data. Consequently, attempting to run these particular requests will not return the responses shown. 

Logging in to Suran API

Logging in to Suran API can be accomplished with a provision and PIN configured through the Administration window in CDM+ (documentation here). Though the provision / PIN combination is typically used with a specific mobile device, it can also be utilized in this case for direct API access.

Documentation

Method

POST

URL

https://{HOST}/api/v2/login

Parameters

provision REQUIRED

The GUID-format string for the provision being used to authenticate.

pin REQUIRED

The PIN associated with the provision as above.

Headers

Provision REQUIRED

The GUID-format string for the provision being used. This should match the provision included as a parameter. 

Examples

 Failed Request (missing required header)
# request
curl -X POST 'https://hosting99.suran.com/api/v2/login'

# response
{
    "errors": [
        {
            "error": "Provision is required in header",
            "status": 422
        }
    ]
}
BASH
 Failed Request (missing required parameters)
# request
curl -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' 'https://hosting99.suran.com/api/v2/login'

# response
{
    "errors": [
        {
            "error": "A provision/pin is required for mobile.",
            "status": 422
        }
    ]
}
BASH
 Failed Request (invalid credentials)
# request
curl -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'provision=2524a545-58bc-426d-9802-f3cca41ebc8e&pin=1111' 'https://hosting99.suran.com/api/v2/login'

# response
{
    "errors": [
        {
            "error": "Provision or pin was incorrect.",
            "status": 422
        }
    ]
}
BASH
 Successful Request
# request
curl -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'provision=2524a545-58bc-426d-9802-f3cca41ebc8e&pin=2222' 'https://hosting99.suran.com/api/v2/login'

# response
# HTTP Status: 200
{
    "data": "You logged into mobile."
}
BASH

Querying an Authenticated Endpoint

After you have logged in to Suran API using the method above, you will be able to query endpoints that require authentication. Note, however, that some endpoints have additional requirements that prevent access (specific roles, CDM+ custom versions, etc.)

The client application you use to query authenticated endpoints will need to be capable of sending and receiving cookies for Suran API to recognize your authenticated status. 

Documentation

Available endpoints are documented and can be viewed in a browser at this link.

Examples

The /authenticated_test endpoint in Suran API provides a way to verify that you have successfully authenticated. In the successful example below, the -c and -b curl flags are used to set and read cookies, respectively, in the specified file (e.g. cookies.txt).

 Failed authenticated_test query
# request
curl -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'testparam=foo' 'https://hosting99.suran.com/api/v2/authenticated_test'

# response
{
    "errors": [
        {
            "error": "You are not logged in",
            "status": 422
        }
    ]
}
BASH
 Successful authenticated_test query
# log in
curl -c cookies.txt -b cookies.txt -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'provision=2524a545-58bc-426d-9802-f3cca41ebc8e&pin=2222' 'https://hosting99.suran.com/api/v2/login'

# request
curl -c cookies.txt -b cookies.txt -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'testparam=foo' 'https://hosting99.suran.com/api/v2/authenticated_test'

# response
# HTTP Status: 200
{
    "data": "test successful. individual_id: 111, provision: "
}
BASH

Logging out of Suran API

Logging out of Suran API will ensure your authenticated session is closed. This endpoint returns a 204 status with no data.

Documentation

Method

DELETE

URL

https://{HOST}/api/v2/logout

Parameters

n/a

Headers

Provision REQUIRED

The GUID-format string for the provision being used. 

Examples

 Successful Login & Logout
# log in
curl -c cookies.txt -b cookies.txt -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'provision=2524a545-58bc-426d-9802-f3cca41ebc8e&pin=2222' 'https://hosting99.suran.com/api/v2/login'

# request to authenticated_test endpoint should succeed when logged in
curl -c cookies.txt -b cookies.txt -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'testparam=foo' 'https://hosting99.suran.com/api/v2/authenticated_test'

# response
# HTTP Status: 200
{
    "data": "test successful. individual_id: 111, provision: "
}

# log out
curl -c cookies.txt -b cookies.txt -X DELETE -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' 'https://hosting99.suran.com/api/v2/logout'

# request to authenticated_test endpoint should fail after logging out
curl -c cookies.txt -b cookies.txt -X POST -H 'Provision: 2524a545-58bc-426d-9802-f3cca41ebc8e' -d 'testparam=foo' 'https://hosting99.suran.com/api/v2/authenticated_test'

# response
{
    "errors": [
        {
            "error": "You are not logged in",
            "status": 422
        }
    ]
}
BASH