API Keys

API Keys

API Key Attributes

api_key

hash


id

integer

/

read-only

Internal identifier for this API Key.
name

string

/

required

Description of this API Key.

  • Must be between 1 and 100 characters in length.
role

string

/

default: organization_admin

The user role of this API Key.

  • On the System Organization (id=1), this may be: system_admin or organization_admin

  • On all other organizations, this must be: organization_admin
active

boolean

/

default: true

The API Key is active and may be used to access SendSage Studio’s API.
api_key

string

/

read-only

The API Key to be used for authentication with the SendSage Studio API.

Get a list of API Keys

Get a list of the API Keys on the current or specified organization.

URL

GET /ga/api/v2/api_keys

System administrators can also use:

GET /ga/api/v2/organization/:organization_id/api_keys

Request Parameters

Provide a name parameter within GET parameters to filter all api keys with that exact description (case insensitive).
Provide a name_contains parameter within GET parameters to filter all api keys that contain that description (case insensitive).

For example to search for the name "admin":

GET /ga/api/v2/organization/6/api_keys?name=admin

Pagination

To query additional records, provide either the page or page_token parameter and optionally the per_page parameter. The page parameter starts at 0.
The per_page parameter defaults to 100 and the maximum allowed is 500.

For example to get the second page:

GET /ga/api/v2/api_keys?&page=1&per_page=100

The response will also contain the following extra keys:

per_page

The number of records per page
num_records

The total number of records that match the query
num_pages

The total number of pages that match the query
page

The current page number (see below)
page_token

The page token to retrieve (see below)
next_page_token

The next page token to retrieve (see below)

This endpoint returns its records paginated. The subscriber records will be sorted by their id in ascending order.

There are two ways to page through the data:

  • Sequentially increment page to specify additional page numbers until you have retrieved every page of the results. When subscribers are added or removed the page boundaries may shift, and it’s possible that some subscribers will be missed between pages or returned on two adjacent pages.

  • Provide in page_token the next_page_token value returned by the most recent call to this API which got the previous page. This guarantees that the next returned page will start immediately after the previous page, with all pages being contiguous and non-overlapping. When a next_page_token of null is returned, that indicates that this is the last page.

If you are presenting a list of pages to the user, you probably want to use page. If you want to retrieve all of the data, page_token is likely what you want.
(When retrieving all data, the page_token method allows SendSage to more efficiently provide the data.)

Both page and page_token may not be specified in the same request.

Response

The response will be a JSON array where each element contains API Key Attributes.

API Keys will the role system_admin will only be returned if the requesting API Key has role system_admin.

Example Request

Note that the JSON response will not be “pretty formatted” as it is below.

GET /ga/api/v2/api_keys

HTTP/1.1 200 OK

{
  "success": true,
  "data": [
    {
      "id": 2,
      "name": "MyString",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTo2ZGNkNGNlMjNkODhlMmVlOTU2OGJhNTQ2YzAwN2M2M2Q5MTMxYzFi"
    },
    {
      "id": 3,
      "name": "some_name",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTo4MDFjMzQyNjlmNzRlZDM4M2ZjOTdkZTMzNjA0YjhhOTA1YWRiNjM1"
    },
    {
      "id": 4,
      "name": "other_name",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTo2MDZlYzZlOWJkOGE4ZmYyYWQxNGU1ZmFkZTNmMjY0NDcxZTgyMjUx"
    },
    {
      "id": 5,
      "name": "other_name",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTplMjUxMjE3MmFiZjhjYzlmNjdmZGQ0OWViNmNhY2YyZGY3MWJiYWQz"
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 4,
  "num_pages": 1
}

Example 2

GET /ga/api/v2/api_keys?name_contains=name

HTTP/1.1 200 OK

{
  "success": true,
  "data": [
    {
      "id": 28,
      "name": "some_name",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTE6ODAxYzM0MjY5Zjc0ZWQzODNmYzk3ZGUzMzYwNGI4YTkwNWFkYjYzNQ=="
    },
    {
      "id": 29,
      "name": "other_name",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTE6NjA2ZWM2ZTliZDhhOGZmMmFkMTRlNWZhZGUzZjI2NDQ3MWU4MjI1MQ=="
    },
    {
      "id": 30,
      "name": "other_name",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTE6ZTI1MTIxNzJhYmY4Y2M5ZjY3ZmRkNDllYjZjYWNmMmRmNzFiYmFkMw=="
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 3,
  "num_pages": 1
}

Create a new API key

Create a new API Key on the current or specified organization.

URL

POST /ga/api/v2/api_keys

System administrators can also use:

POST /ga/api/v2/organizations/:organization_id/api_keys

Request Parameters

The request body should be a JSON hash of API Key Attributes.

API Keys with the role system_admin can only be created on the System Organization and only by an API Key that also has the role system_admin.

Response

The response body will be a JSON hash of API Key Attributes.

Example Request

Note that the JSON response will not be “pretty formatted” as it is below.

POST /ga/api/v2/api_keys

{
  "api_key": {
    "name": "Api Key Name",
    "active": true
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 46,
    "name": "Api Key Name",
    "role": "organization_admin",
    "active": true,
    "api_key": "MTc6YzFmZTNhN2I0ODdmNjZhNmFjOGM3ZTQ3OTRiYzU1YzMxYjBlZjQwMw=="
  },
  "error_code": null,
  "error_message": null
}

Update an existing API key

URL

PUT /ga/api/v2/api_keys/:id

System administrators can also use:

PUT /ga/api/v2/organizations/:organization_id/api_keys/:id

Request Parameters

The request body should be a JSON hash of API Key Attributes.

API Keys can only be updated to the role system_admin on the System Organization and only by an API Key that also has the role system_admin.

Response

The response body will be a JSON hash of API Key Attributes.

Example Request

Note that the JSON response will not be “pretty formatted” as it is below.

PUT /ga/api/v2/api_keys/71

{
  "api_key": {
    "active": false
  }
}

HTTP/1.1 200 OK

{
  "success": true,
  "data": {
    "id": 71,
    "name": "other_name",
    "role": "organization_admin",
    "active": false,
    "api_key": "Mjc6ZTI1MTIxNzJhYmY4Y2M5ZjY3ZmRkNDllYjZjYWNmMmRmNzFiYmFkMw=="
  },
  "error_code": null,
  "error_message": null
}

Delete an API Key

URL

DELETE /ga/api/v2/api_keys/:id

System administrators can also use:

DELETE /ga/api/v2/organizations/:organization_id/api_keys/:id

Response

An empty successful response to this request indicates that the API Key was successfully deleted.

Example Request

Note that the JSON response will not be “pretty formatted” as it is below.

DELETE /ga/api/v2/api_keys/92

HTTP/1.1 200 OK

{
  "success": true,
  "data": null,
  "error_code": null,
  "error_message": null
}
 "API V2"
"Autoresponders API"