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 organizations, this must be: `organization_admin`

    active (boolean; default: `true`):

        The API Key is active and may be used to access InboxFirst's API.

    api_key (string; read-only):

        The API Key to be used for authentication with the InboxFirst 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

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:

Key	Description
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 InboxFirst 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.

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

Request Parameters¶

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

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

Request Parameters¶

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

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

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
}