This method will accept user credentials and return information about the user (if the details are correct) along with an API token which can be used.

This method must be sent with an X-Auth-Application header. You do not need to sent any other authentication headers with this request.

URL

/api/v2/authentication/authenticate

Supported Parameters

• username - the user's username
• password - the user's password
• two_factor_code - the user's two factor authentication code (if using two factor authentication)
• account - the account from which you wish to search (optional, if you do not send an account parameter, the system will return an array of all users which match those credentials - see below).

Example JSON - Successful responses

Response from a successful authentication without an account parameter

This method will return a hash with a status of 'Authenticated' along with an array of all authenticated users along with their API tokens and the account they belong to. The users array will only include users where API access has been enabled by an administrator.

{
  "status": "Authenticated",
  "users": [
    {
      "id": 6,
      "username": "adam",
      "first_name": "Adam",
      "last_name": "Cooke",
      "email_address": "adam@atechmedia.com",
      "time_zone": "London",
      "created_at": "2012-01-12T22:09:01+00:00",
      "activated?": true,
      "invite_code": null,
      "permissions": {
        "admin": true,
        "reporting": true,
        "tickets": true,
        "api": true
      },
      "account": {
        "name": "aTech Media",
        "permalink": "atech",
        "domain": "atech.sirportly.com",
        "domain_with_protocol": "https://atech.sirportly.com",
        "enabled": true
      },
      "api_token": {
        "token": "[token here]",
        "secret": "[secret here]"
      }
    },
    {
      "id": 36,
      "username": "adam",
      "first_name": "Adam",
      "last_name": "Cooke",
      "email_address": "adam@atechmedia.com",
      "time_zone": "London",
      "created_at": "2012-02-01T16:07:56+00:00",
      "activated?": true,
      "invite_code": null,
      "permissions": {
        "admin": true,
        "reporting": true,
        "tickets": true,
        "api": true
      },
      "account": {
        "name": "Fibreband Ltd",
        "permalink": "fibreband",
        "domain": "fibreband.sirportly.com",
        "domain_with_protocol": "https://fibreband.sirportly.com",
        "enabled": true
      },
      "api_token": {
        "token": "[token here]",
        "secret": "[secret here]"
      }
    }
  ]
}

Response from a successful authentication with an account parameter

This method will return a hash with a status of 'Authenticated' along with the details of the authenticated user.

{
  "status": "Authenticated",
  "user": {
    "id": 6,
    "username": "adam",
    "first_name": "Adam",
    "last_name": "Cooke",
    "email_address": "adam@atechmedia.com",
    "time_zone": "London",
    "created_at": "2012-01-12T22:09:01+00:00",
    "activated?": true,
    "invite_code": null,
    "permissions": {
      "admin": true,
      "reporting": true,
      "tickets": true,
      "api": true
    },
    "account": {
      "name": "aTech Media",
      "permalink": "atech",
      "domain": "atech.sirportly.com",
      "domain_with_protocol": "https://atech.sirportly.com",
      "enabled": true
    },
    "api_token": {
      "token": "[token here]",
      "secret": "[secret here]"
    }
  }
}

Successful authentication but API access is disabled for the user (when an account param is passed)

If you attempt to authenticate a user and pass an account parameter but the user is not permitted to use the API you will receive the response below. An administrator of the account can enable it for them (it is disabled by default).

{
  "status": "APIAccessDisabled"
}

Example JSON - invalid login responses

Response from invalid credentials

This method will return a hash with a status of 'InvalidCredentials' along with the credentials and permalink of the account we received.

{
  "status": "InvalidCredentials",
  "username": "jogn",
  "password": "invalidpassword",
  "account": "acme"
}

Response from valid credentials, with an account provided but with two factor authentication required and not set up for the user

This method will return a hash with a status of 'TwoFactorRequired'.

{
  "status": "TwoFactorRequired"
}

Response from valid credentials, with an account provided but with an invalid two factor authentication code

This method will return a hash with a status of 'InvalidTwoFactorCode'.

{
  "status": "InvalidTwoFactorCode"
}

Response from valid credentials, with an account provided but with a lockout from too many incorrectly entered two factor authentication codes

This method will return a hash with a status of 'TwoFactorLocked'.

{
  "status": "TwoFactorLocked"
}

Response from valid credentials, with an account provided but connecting from an invalid IP address where network restrictions have been enabled

This method will return a hash with an error of 'NotPermittedFromIPAddress', along with the ip - the ip address the authentication attempt was made from.

{
  "error": "NotPermittedFromIPAddress",
  "ip": "127.0.0.1"
}

Response from valid credentials, with an incorrect account provided

This method will return a hash with an error of 'AccountNotFound', along with a message containing the permalink of the account received.

{
  "error": "AccountNotFound",
  "message": "No account found matching 'acme'"
}