Auth

The Authentication APIs are used for accessing the Shopmonkey API.

POST/v3/auth/api_key

New API Key

Generate a new API Key with an optional expiration based on the current session user and location. If an expiration is 0 or not provided, will create a non-expiring API Key.

Body parameters

Consumes

The following content type is required: application/json

  • Name
    audience
    Type
    one of: 'shop', 'hq' Required
    Description
    The audience to generate the API key for. If not provided, will default to the current audience of the user.
  • Name
    expires
    Type
    integer
    Description
    The number of days until the API key expires. If not provided, will default to 100 years. (ex: 30d)
  • Name
    name
    Type
    string Required
    Description
    A name that we will use to identify the API key

Produces

The response content type: application/json

200 Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if success = false
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message
  • Name
    data
    Type
    object Required
    Description

Properties for data object

  • Name
    token
    Type
    string Required
    Description
    the API key

4xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

5xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

Example Request
application/json

POST
/v3/auth/api_key
curl https://api.shopmonkey.cloud/v3/auth/api_key \
  -H "Authorization: Bearer ${SM_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{}'

Example Response
application/json

{
  "success": true,
  "data": {
    "token": "token"
  }
}
DELETE/v3/auth/api_key/:id

Delete API Key

Delete one API key

URL parameters

  • Name
    id
    Type
    string Required
    Description
    the id for the API key

Body parameters

Consumes

The following content type is required: application/json

  • Name
    invalidatedReason
    Type
    string
    Description
    The reason for deleting the API key

Produces

The response content type: application/json

200 Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if success = false
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

4xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

5xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

Example Request
application/json

DELETE
/v3/auth/api_key/:id
curl https://api.shopmonkey.cloud/v3/auth/api_key/:id \
  -H "Authorization: Bearer ${SM_TOKEN}" \
  -X DELETE -H 'Content-Type: application/json' \
  --data '{}'

Example Response
application/json

{
  "success": true
}
GET/v3/auth/api_key

List s

Find all s

Query String parameters

  • Name
    collate
    Type
    boolean
    Description
    if set to true, use natural sort collation when used with orderBy
  • Name
    ids
    Type
    array
    Description
  • Name
    limit
    Type
    number
    Description
    the limit on the number of records to return
  • Name
    orderby
    Type
    string
    Description
    the order instructions for the result
  • Name
    params
    Type
    string
    Description
    additional request specific params
  • Name
    skip
    Type
    number
    Description
    the number of records to skip for a paginated result
  • Name
    where
    Type
    string
    Description
    an object to use for filtering the results

Produces

The response content type: application/json

200 Response

  • Name
    data
    Type
    array Required
    Description
    an array of items
  • Name
    meta
    Type
    object
    Description
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

Properties for meta object

  • Name
    hasMore
    Type
    boolean Required
    Description
    if there are more records available
  • Name
    total
    Type
    number Required
    Description
    the total number of records

4xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

5xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

Example Request

GET
/v3/auth/api_key
curl https://api.shopmonkey.cloud/v3/auth/api_key \
  -H "Authorization: Bearer ${SM_TOKEN}"

Example Response
application/json

{
  "data": [
    {
      "id": "id",
      "createdDate": "createdDate",
      "name": null,
      "expirationDate": "expirationDate",
      "user": {
        "firstName": "firstName",
        "lastName": "lastName"
      }
    }
  ],
  "success": true
}
POST/v3/auth/login

Login

The endpoint for logging in and receiving a login session

Body parameters

Consumes

The following content type is required: application/json

  • Name
    audience
    Type
    one of: 'admin', 'api', 'api_hq', 'app', 'hq', 'mobile', 'mobile_android', 'mobile_ios', 'ops', 'shop'
    Description
    The app the user is logging into
  • Name
    email
    Type
    string Required
    Description
    The user's email address
  • Name
    password
    Type
    string Required
    Description
    The user's password

Produces

The response content type: application/json

200 Response

  • Name
    data
    Type
    object Required
    Description
  • Name
    success
    Type
    boolean Required
    Description
    Returns true if the login attempt was successful

Properties for data object

  • Name
    algoliaAuthToken
    Type
    string Required
    Description
    Global Search Algolia search token
  • Name
    algoliaCannedServiceSearchToken
    Type
    string Required
    Description
    Canned Service Algolia search token
  • Name
    branch
    Type
    string Required
    Description
    SM_BRANCH value
  • Name
    companySearchAppId
    Type
    string
    Description
    Company data search application id
  • Name
    companySearchAuthToken
    Type
    string
    Description
    Company data search token
  • Name
    entitlements
    Type
    array Required
    Description
  • Name
    globalSearchAppId
    Type
    string Required
    Description
    Global Search Application id
  • Name
    hqEnabled
    Type
    boolean Required
    Description
    If user has access to any HQ enabled company
  • Name
    natsUserCredentials
    Type
    string Required
    Description
    Nats User Credentials
  • Name
    sessionId
    Type
    string Required
    Description
    The unique session identifier
  • Name
    token
    Type
    string Required
    Description
    JWT Authorization Token
  • Name
    user
    Type
    object Required
    Description

Properties for user object

  • Name
    color
    Type
    one of: aqua, blue, brown, green, orange, purple, red, yellow
    Description
  • Name
    companyId
    Type
    string Required
    Description
    The unique company identifier
  • Name
    companyLocations
    Type
    array
    Description
    A list of all company locations (even ones the user does not have access to) — only returned on HQ login/session requests
  • Name
    companyWideAccess
    Type
    boolean Required
    Description
    Whether the user has company wide access or location specific access
  • Name
    createdDate
    Type
    string Required
    Description
    The user's creation date
  • Name
    currentLocationId
    Type
    string
    Description
    The unique identifier of the last location which the user logged into
  • Name
    customPhotoId
    Type
    string Required
    Description
    the custom photo id for the avatar
  • Name
    customPhotoUrl
    Type
    string Required
    Description
    the custom photo url for the avatar
  • Name
    email
    Type
    string Required
    Description
    The user's email address
  • Name
    firstName
    Type
    string Required
    Description
    The user's given name
  • Name
    googlePhotoDisabled
    Type
    boolean Required
    Description
    if the google profile photo is disabled
  • Name
    googlePhotoUrl
    Type
    string Required
    Description
    the google profile photo url for the user
  • Name
    id
    Type
    string Required
    Description
    The unique identifier for the user
  • Name
    isSMEmployee
    Type
    boolean
    Description
    true if the user is a ShopMonkey employee
  • Name
    lastName
    Type
    string Required
    Description
    The user's family name
  • Name
    locations
    Type
    array
    Description
  • Name
    permissions
    Type
    array Required
    Description
  • Name
    preferredLanguage
    Type
    one of: en, en_US, fr_CA, es_MX Required
    Description
  • Name
    userRoleIds
    Type
    array
    Description
  • Name
    userRoleNames
    Type
    array
    Description
  • Name
    company
    Type
    object
    Description
  • Name
    location
    Type
    object
    Description

Properties for company object

  • Name
    companyBusinessInfo
    Type
    object
    Description
  • Name
    createdDate
    Type
    string Required
    Description
    The company's creation date
  • Name
    hqEnabled
    Type
    boolean Required
    Description
    Returns true of the user is part of a company that has HQ enabled
  • Name
    name
    Type
    string
    Description
    The company name
  • Name
    selfScheduledUpgrade
    Type
    boolean Required
    Description
    If the company was upgraded from v1, true if self-scheduled
  • Name
    upgradeScheduledDate
    Type
    string Required
    Description
    The date the company is scheduled to upgrade from v1
  • Name
    upgraded
    Type
    boolean Required
    Description
    Returns true if the company has been upgraded from v1
  • Name
    upgradedDate
    Type
    string Required
    Description
    The date the company was upgraded from v1
  • Name
    whiteLabelBlobId
    Type
    string
    Description
    The white label blob id

Properties for companyBusinessInfo object

  • Name
    individualTaxId
    Type
    boolean Required
    Description
    true if the company has an individual tax id

Properties for location object

  • Name
    address1
    Type
    string
    Description
    The first line of the location address
  • Name
    address2
    Type
    string
    Description
    The second line of the location address
  • Name
    city
    Type
    string
    Description
    The location city
  • Name
    country
    Type
    string
    Description
    The location country
  • Name
    createdDate
    Type
    string Required
    Description
    The location's creation date
  • Name
    locationConfig
    Type
    object
    Description
  • Name
    name
    Type
    string
    Description
    The location name
  • Name
    postalCode
    Type
    string
    Description
    The location postal code
  • Name
    state
    Type
    string
    Description
    The location state
  • Name
    timezone
    Type
    string
    Description
    The location timezone

Properties for locationConfig object

  • Name
    requireMileageRecordBeforeInvoice
    Type
    boolean Required
    Description
    True if the location requires mileage recorded before an order can be invoiced

4xx Response

  • Name
    code
    Type
    string
    Description
    The error code
  • Name
    data
    Type
    object
    Description
    An optional object containing relevant error data
  • Name
    documentation_url
    Type
    string
    Description
    An optional link to the documentation for the error
  • Name
    message
    Type
    string
    Description
    the error message if not successful
  • Name
    success
    Type
    boolean Required
    Description
    if successful, will be true. if not successful, will be false and message will contain a human readable error message

Example Request
application/json

POST
/v3/auth/login
curl https://api.shopmonkey.cloud/v3/auth/login \
 \
  -H 'Content-Type: application/json' \
  --data '{ "email" : "value", "password" : "value" }'

Example Response
application/json

{
  "success": true,
  "data": {
    "token": "token",
    "algoliaAuthToken": null,
    "sessionId": "sessionId",
    "user": {
      "id": "id",
      "locationId": "locationId",
      "companyId": "companyId",
      "firstName": "firstName",
      "lastName": "lastName",
      "permissions": [
        "permissions"
      ]
    }
  }
}
POST/v3/auth/logout

Logout

The endpoint for logging out and invalidating the login session

Produces

The response content type: application/json

200 Response

  • Name
    success
    Type
    boolean Required
    Description

Example Request
application/json

POST
/v3/auth/logout
curl https://api.shopmonkey.cloud/v3/auth/logout \
  -H "Authorization: Bearer ${SM_TOKEN}" \
  -H 'Content-Type: application/json' \
  --data '{}'

Example Response
application/json

{
  "success": true
}