API Keys

• Table of Contents
• API Key Attributes
• Get a list of API Keys
  • URL
  • Request Parameters
  • Pagination
  • Response
  • Example Request
  • Example 2
• Create a new API key
  • URL
  • Request Parameters
  • Response
  • Example Request
• Update an existing API key
  • URL
  • Request Parameters
  • Response
  • Example Request
• Delete an API Key
  • URL
  • Response
  • Example Request

API Key Attributes

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:

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
}