GreenArrow Email Software Documentation

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 GreenArrow Studio’s API.
api_key

string

/

read-only

The API key to be used for authentication with the GreenArrow Studio API.

Get a List of API Keys

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

URL

Get the list of API keys on the current organization:

GET /ga/api/v2/api_keys

System administrators can also get the list of API keys on a specific organization:

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

Parameters

name

string

Get a list of API keys with this exact, case-insensitive name.
name_contains

string

Get a list of API keys whose names containing this case-insensitive string.
order_by

string

Specify an API key field to sort the results by. Can be name or id.

Defaults to id.

For example to search for the API key named admin in organization 6:

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

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.

This endpoint returns paginated records.

Example

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": "Primary API Account",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTo2ZGNkNGNlMjNkODhlMmVlOTU2OGJhNTQ2YzAwN2M2M2Q5MTMxYzFi"
    },
    {
      "id": 3,
      "name": "Secondary API Account",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTo4MDFjMzQyNjlmNzRlZDM4M2ZjOTdkZTMzNjA0YjhhOTA1YWRiNjM1"
    },
    {
      "id": 4,
      "name": "Client Services",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTo2MDZlYzZlOWJkOGE4ZmYyYWQxNGU1ZmFkZTNmMjY0NDcxZTgyMjUx"
    },
    {
      "id": 5,
      "name": "Integrated Offerings",
      "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=aPi


HTTP/1.1 200 OK


{
  "success": true,
  "data": [
    {
      "id": 27,
      "name": "Primary API Account",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTE6NmRjZDRjZTIzZDg4ZTJlZTk1NjhiYTU0NmMwMDdjNjNkOTEzMWMxYg=="
    },
    {
      "id": 28,
      "name": "Secondary API Account",
      "role": "organization_admin",
      "active": true,
      "api_key": "MTE6ODAxYzM0MjY5Zjc0ZWQzODNmYzk3ZGUzMzYwNGI4YTkwNWFkYjYzNQ=="
    }
  ],
  "error_code": null,
  "error_message": null,
  "page": 0,
  "per_page": 100,
  "num_records": 2,
  "num_pages": 1
}

Get a Single API Key

Get all the basic details of a single API key.

URL

GET /ga/api/v2/api_keys/:id

Request Parameters

id

integer

The id of the API key to get

Response

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

Example

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

GET /ga/api/v2/api_keys/55


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "id": 55,
    "name": "Integrated Offerings",
    "role": "organization_admin",
    "active": true,
    "api_key": "MjE6ZTI1MTIxNzJhYmY4Y2M5ZjY3ZmRkNDllYjZjYWNmMmRmNzFiYmFkMw=="
  },
  "error_code": null,
  "error_message": null
}

Create an 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

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": 61,
    "name": "Api Key Name",
    "role": "organization_admin",
    "active": true,
    "api_key": "MjM6YzFmZTNhN2I0ODdmNjZhNmFjOGM3ZTQ3OTRiYzU1YzMxYjBlZjQwMw=="
  },
  "error_code": null,
  "error_message": null
}

Update an API Key

URL

PUT /ga/api/v2/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

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

PUT /ga/api/v2/api_keys/86


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


HTTP/1.1 200 OK


{
  "success": true,
  "data": {
    "id": 86,
    "name": "Integrated Offerings",
    "role": "organization_admin",
    "active": false,
    "api_key": "MzM6ZTI1MTIxNzJhYmY4Y2M5ZjY3ZmRkNDllYjZjYWNmMmRmNzFiYmFkMw=="
  },
  "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

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

DELETE /ga/api/v2/api_keys/107


HTTP/1.1 200 OK


{
  "success": true,
  "data": null,
  "error_code": null,
  "error_message": null
}

 GreenArrow Studio API
Autoresponders API 

Copyright © 2012–2024 GreenArrow Email