Before You Begin:
- You have staff access to manage integration settings. API Keys are created and managed at API Key Permissions, available under Settings, Advanced Settings section.
- You have a server-based application that can store a secret securely and communicate over HTTPS.
Step-by-Step Instructions
This document provides background information on API Key Authentication, covering what it is, when to use it, and how to use it.
What is API Key Authentication
GrowthZone supports two general forms of Authentication: User and Server.
User authentication is the process of a user providing who they claim to be, either by entering credentials or delegating the burden of proof to an external Identity Server.
Server authentication is the process by which a server, or more specifically an Application, identifies itself in the absence of any physical user involvement.
GrowthZone supports Server authentication by issuing unique API Keys for each Application that requires authentication. On the outside, an API Key is just a string of random characters, but it is designed to be sufficiently long and unique that guessing it is extremely difficult.
When should API Key Authentication be used?
An API Key is suitable under the following conditions:
- You have an application that requires access to GrowthZone data.
- Your application's data requirements can be satisfied without the context of an individual user.
- You can store the API key in a secure place.
- Your application can use HTTPS.
- Your application is server-based and can communicate over backchannels.
An API Key is not suitable when:
- You need to identify as a user, as an API Key can only identify the application.
- Your application runs client-side, where the API Key could be exposed publicly.
Security of an API Key
Unlike other forms of API access, an API Key doesn't expire and cannot be revoked without deleting the configuration in GrowthZone. To manage or remove a key, go to Settings, Advanced Settings section, and click API Key Permissions.
How does API Key Authentication work?
API Key authentication uses the API Key scheme with the Authorization header for each HTTPS request.
Host: example.com
Authorization: ApiKey [API KEY]
GET /api/contacts/root/claims
Common Pitfalls
- Exposing the key client-side: Never embed an API Key in a client-side application or public repository. Because the key has no expiration and identifies the application, anyone who obtains it has access until you delete it.
- Forgetting that keys can't be rotated automatically: An API Key cannot be revoked or set to expire. If a key is compromised, the only remedy is to delete the configuration at API Key Permissions (Settings, Advanced Settings section) and issue a new one.