Create an auth token

Returns a new access token.

URL: https://api.courier.com/auth/issue-token

Method: POST

Body Parameters

scopestringrequired

Permissions to apply to the token.

expires_instring

A string describing the time span the token is valid for. Can also be a number instead of a string (in seconds). See https://github.com/vercel/ms for examples.

Responses

status: 200 OK

tokenstring

The issued token.

status: 400 Bad Request

messagestring

A message describing the error that occurred.

typestring

[invalid_request_error] The type of error that occurred.

Request Example

cURL

curl --request POST \
     --url https://api.courier.com/auth/issue-token \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
  "scope": "user_id:user_id_you_want_to_create_scope_for read:messages",
  "expires_in": "2 days"
}
'

Node.js

// Dependencies to install:
// $ npm install node-fetch --save

const fetch = require('node-fetch');

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "scope": "user_id:user_id_you_want_to_create_scope_for read:messages",
    "expires_in": "2 days"
  })
};

fetch('https://api.courier.com/auth/issue-token', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Ruby

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.courier.com/auth/issue-token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request.body = "{\"scope\":\"user_id:user_id_you_want_to_create_scope_for read:messages\",\"expires_in\":\"2 days\"}"

response = http.request(request)
puts response.read_body

Python

# Dependencies to install:
# $ python -m pip install requests

import requests

url = "https://api.courier.com/auth/issue-token"

payload = {
  "scope": "user_id:user_id_you_want_to_create_scope_for read:messages",
  "expires_in": "2 days"
}
headers = {
  "Accept": "application/json",
  "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Go

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.courier.com/auth/issue-token"

  payload := strings.NewReader("{\"scope\":\"user_id:user_id_you_want_to_create_scope_for read:messages\",\"expires_in\":\"2 days\"}")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Accept", "application/json")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

PHP

<?php
// Dependencies to install:
// $ composer require guzzlehttp/guzzle

require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.courier.com/auth/issue-token', [
  'body' => '{"scope":"user_id:user_id_you_want_to_create_scope_for read:messages","expires_in":"2 days"}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();

Responses Example

{
  "token": "5e2b2615.05efbb3acab9172f88dd3f6f"
}

{
  "message": "Error Message",
  "type": "invalid_request_error"
}

Usage

An auth token can be used as a bearer token in place of a normal API Key for the following endpoints:

• GET /brands (must have read:brands scope).
• PUT | DELETE /brands (must have write:brands scope).
• GET /brands/:id (must have read:brands or read:brands:<id> for single brand access).
• PUT | DELETE /brands/:id (must have write:brands or write:brands:<id> for single brand access).
• PUT | PATCH | DELETE /users/:user_id/tokens/:token (must have write:user-tokens scope).
• GET /users/:user_id/tokens/:token (must have read:user-tokens scope).
• PUT | PATCH | DELETE /users/:user_id/preferences/:topic_id (must have write:preferences scope).
• GET /users/:user_id/preferences (must have read:preferences scope).
• GET /users/:user_id/preferences/:topic_id (must have read:preferences scope).
• GraphQL (POST) /client/q Required permissions depend on query / mutation.
  • messages Requires read:messages scope.

Notes:

• Endpoints that are tied to a user_id require the user_id to be listed in the scope field (i.e user_id:123)

Available Scopes

• user_id:<user-id> - Gives the token access to a given user. Multiple can be listed. Ex user_id:pigeon user_id:bluebird. User ID scopes must be used in conjunction with other scopes to specify which resources of the user the token can access.
• read:messages - Gives the token access to read messages. Must be used in conjunction with one or more user_ids.
• read:user-tokens - Gives the token access to read user tokens. Must be used in conjunction with one or more user_id scopes.
• write:user-tokens - Gives the token access to write user tokens. Must be used in conjunction with one or more user_id scopes.
• read:brands[:<brand_id>] Give the token access to read brands, optionally restricted to a specific brand_id. Examples read:brands, read:brands:my_brand.
• write:brands[:<brand_id>] Give the token access to read brands, optionally restricted to a specific brand_id. Examples write:brands, write:brands:my_brand.
• inbox:read:messages Give the token access to read inbox messages.
• inbox:write:events Give the token access to write inbox events, such as mark message as read.
• read:preferences Give the token access to read user preferences.
• write:preferences Give the token access to write user preferences.