API Keys

On this page, we'll explore the Authentication API that let you programmatically manage your account and API keys.

ENDPOINTS

POST /auth/v1/api-keys
GET /auth/v1/api-keys/:id
PUT /auth/v1/api-keys/:id
DELETE /auth/v1/api-keys/:id

The API key object

Properties

Name
key_id
Type
string
Description
Unique identifier for the API key.
Name
nickname
Type
string
Description
The nickname of the API key.
Name
key
Type
string
Description
The hashed API key.
Name
prefix
Type
string
Description
The prefix (first 10 characters) of the API key.
Name
permissions
Type
array
Description
The permissions of the API key.
Name
allowed_urls
Type
array
Description
The URLs that the API key is allowed to access.
Name
is_active
Type
boolean
Description
Whether the API key is active.
Name
revoked_at
Type
timestamp | null
Description
The timestamp of when the API key was revoked.
Name
created_at
Type
timestamp
Description
The timestamp of when the API key was created.
Name
updated_at
Type
timestamp
Description
The timestamp of when the API key was last updated.

The API Key object

{
  "key_id": "hSIhXBhNe8X1d8Et",
  "nickname": "Exhibitors",
  "key": "eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk",
  "prefix": "hSIhXBhNe8X1d8Et",
  "permissions": ["catalogs:read", "catalogs:write", "content:delete", "content:write"],
  "allowed_urls": ["https://domain.com"],
  "is_active": true,
  "revoked_at": null,
  "created_at": 692233200,
  "updated_at": 705103200
}

API key permissions structure

Every endpoint requires an API Key with a specific scope to properly authorize requests. The scope is a string that represents the permissions of the API key, and is structured as follows:

"<resource>:<action>"

Where <resource> is the resource you are trying to access, and <action> is the action you are trying to perform on the resource.

For example, to access the Retrieve a Catalog endpoint, you would need an API Key with the scope catalogs:read. To update a catalog, you would need an API Key with the scope catalogs:write. And to delete a catalog, you would need an API Key with the scope catalogs:delete.

POST/auth/v1/api-keys

Create an API key

Upon successful creation, the API key is returned in plaintext (this is the only time it is returned in plaintext). It is highly recommended to store the key field in a secure location, and only use the prefix field to identify the API key in the database.

Optional attributes

Name
nickname
Type
string
Description
The nickname for the API key.
Name
permissions
Type
array
Description
The permissions for the API key. Must be a subset of the account's permissions. Defaults to [].
Name
allowed_urls
Type
array
Description
The URLs that the API key is allowed to make requests from. Defaults to [].

POST /auth/v1/api-keys

API KEY SCOPE

api-keys:write

curl https://api.waygomaps.com/auth/v1/api-keys \
    -X POST \
    -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
    -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9" \
    -d '{
      "nickname": "Catalog API Key",
      "permissions": ["catalogs:read", "catalogs:write", "content:delete", "content:write"],
      "allowed_urls": ["https://domain.com"]
    }'

Response

{
  "key": "eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk",
  "key_id": "hSIhXBhNe8X1d8Et",
  "nickname": "Catalog API Key",
  "prefix": "hSIhXBhNe8X1d8Et",
  "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
  "permissions": ["catalogs:read", "catalogs:write", "content:delete", "content:write"],
  "allowed_urls": ["https://domain.com"],
  "is_active": true,
  "revoked_at": null,
  "created_at": 692233200,
  "updated_at": 705103200
}

GET/auth/v1/api-keys/:id

Retrieve an API key

This endpoint allows you to retrieve an API Key by providing its Key ID.

GET /auth/v1/api-keys/:id

API KEY SCOPE

api-keys:read

curl https://api.waygomaps.com/auth/v1/api-keys/hSIhXBhNe8X1d8Et \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9"

Response

{
  "key_id": "hSIhXBhNe8X1d8Et",
  "account_id": "n33f9h0fh9324hf9h439fh9h2f9h93h9",
  "nickname": "Catalog API Key",
  "prefix": "hSIhXBhNe8X1d8Et",
  "permissions": ["catalogs:read", "catalogs:write", "content:delete", "content:write"],
  "allowed_urls": ["https://domain.com"],
  "is_active": true,
  "revoked_at": null,
  "created_at": 692233200,
  "updated_at": 705103200
}

PUT/auth/v1/api-keys/:id

Update an API key

This endpoint allows you to perform an update on an API Key.

Only the attributes included in the request will be updated in the API Key object, ie. whichever attributes are not included in the request will not be changed.

The permissions of an API Key cannot be updated. If you require a key with different permissions, you will need to create a new API Key with the desired permissions.

Optional attributes

Name
nickname
Type
string
Description
The nickname for the API key.
Name
allowed_urls
Type
array
Description
The URLs that the API key is allowed to make requests from.

PUT /auth/v1/api-keys/:id

API KEY SCOPE

api-keys:write

curl -X PUT https://api.waygomaps.com/auth/v1/api-keys/hSIhXBhNe8X1d8Et \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n39q9h0ph9324hf9h4vksh9h2f9h03hl" \
  -d '{
    "nickname": "Catalog API Key",
    "allowed_urls": ["https://domain.com"]
  }'

Response

{
  "key_id": "hSIhXBhNe8X1d8Et",
  "account_id": "n39q9h0ph9324hf9h4vksh9h2f9h03hl",
  "nickname": "Catalog API Key",
  "prefix": "hSIhXBhNe8X1d8Et",
  "permissions": ["catalogs:read", "catalogs:write", "content:delete", "content:write"],
  "allowed_urls": ["https://domain.com"],
  "is_active": true,
  "revoked_at": null,
  "created_at": 692233200,
  "updated_at": 705103200
}

DELETE/auth/v1/api-keys/:id

Revoke an API key

This endpoint revokes an API Key, making it inactive.

Be extremely cautious using this endpoint.

DELETE /auth/v1/api-keys/:id

API KEY SCOPE

api-keys:delete

curl -X DELETE https://api.waygomaps.com/auth/v1/api-keys/hSIhXBhNe8X1d8Et \
  -H "Waygo-API-Key: eyJhbGciOiJIU...sXSJE_1AJgMEnI_g-WTerk" \
  -H "Waygo-Account: n33f9h0fh9324hf9h439fh9h2f9h93h9"