Login
Endpoints for authentication, beginning a Session

Learn how to use Suran API on the Suran Help Center.

After a successful login, provide the session cookie in headers to request Session resources.

>>>

POST /api/v2/login
Login, beginning a Session

Headers

Header name Description
Provision
required 		Web/Mobile/API Provision UUID

Params

Param name Description
provision
optional

Mobile provision

Validations:

  • Must be a String
pin
optional

Pin for mobile

Validations:

  • Must be a String

Returns

Code: 200

Description:

Successful login

Param name Description
data
required

Message returned for successful login

Validations:

  • Must be a String

Code: 401

Description:

Unauthorized

Param name Description
errors
required

Errors returned by request

Validations:

  • Must be an Array of nested elements
errors[error]
required

Why the request failed

Validations:

  • Must be a String
errors[status]
required

HTTP response code

Validations:

  • Must be a Integer

Code: 404

Description:

Not Found

Param name Description
errors
required

Errors returned by request

Validations:

  • Must be an Array of nested elements
errors[error]
required

Why the request failed

Validations:

  • Must be a String
errors[status]
required

HTTP response code

Validations:

  • Must be a Integer

Code: 422

Description:

Unprocessable Entity

Param name Description
errors
required

Errors returned by request

Validations:

  • Must be an Array of nested elements
errors[error]
required

Why the request failed

Validations:

  • Must be a String
errors[status]
required

HTTP response code

Validations:

  • Must be a Integer

Code: 500

Description:

Internal Server Error

Param name Description
errors
required

Errors returned by request

Validations:

  • Must be an Array of nested elements
errors[error]
required

Why the request failed

Validations:

  • Must be a String
errors[status]
required

HTTP response code

Validations:

  • Must be a Integer

Errors

Code Description
404 Data source query failed
422 Invalid parameter(s)
422 Provision header missing
422 Invalid provision
422 Under maintenance
422 Incorrect host for provision
422 Establishing session failed
422 Privilege to perform the action was not found
422 Provision/PIN missing
422 Provision/PIN incorrect
422 Provision does not exist
500 No connection to data source

Examples

POST /api/v2/login
{
  "pin": "4321",
  "provision": "11112222-3333-4444-5555-666677778888"
}
422
{
  "errors": [
    {
      "error": "Provision or pin was incorrect.",
      "status": 422
    }
  ]
}
POST /api/v2/login
{
  "pin": "1234",
  "provision": "12345678-1111-2222-3333-123412341234"
}
200
{
  "data": "Login successful"
}
POST /api/v2/login
{
  "pin": "1234",
  "username": "Bob"
}
422
{
  "errors": [
    {
      "error": "Provision/PIN is required for login",
      "status": 422
    }
  ]
}
POST /api/v2/login
{
  "pin": "4321",
  "provision": "baaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
}
422
{
  "errors": [
    {
      "error": "setup failed",
      "status": 422
    }
  ]
}