Suran API
Authenticating
Working with authenticated endpoints in Suran API is a three-step process:
- Log in with a provision and PIN to start an authenticated session.
- Query the relevant endpoint(s) according to specified documentation.
- 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
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'
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
# request
curl -X POST 'https://hosting99.suran.com/api/v2/login'
# response
{
"errors": [
{
"error": "Provision is required in header",
"status": 422
}
]
}
# 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
}
]
}
# 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
}
]
}
# 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."
}
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
).
# 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
}
]
}
# 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: "
}
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
# 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
}
]
}