Introduction

To access data stored in Penzle, you must authenticate your API requests. This is done by including an API key in your requests that identifies your Penzle account and the project you want to access.

Types of authentication

Penzle provides two types of authentication for API access:

  1. API key authentication
  2. OAuth2 authentication

1. API Key authentication

Your API requests are validated by Penzle using the API keys associated with your account. Whenever you attempt to use the Penzle API without providing a key, the backend API will throw an exception that can be interpreted as unauthorized. Getting an authentication error could be if the key is invalid or outdated.

There are two types of API keys in Penzle:

  1. Content Delivery API (CDA) Key: This key is used to retrieve and deliver content from Penzle's cloud-based platform to your application. The CDA key is public and can be safely embedded in your client-side code.
  2. Content Management API (CMA) Key: This key is used to manage and manipulate content within your Penzle account. The CMA key is private and should not be embedded in client-side code or shared with unauthorized parties.

To obtain your API keys, log into your Penzle account, go to Projects -> API tokens, and create a new API key. Once you have your API keys, you can include them in your API requests by including the following header:

Authorization: Bearer {API_KEY}

Note that API keys are tied to specific projects and environments in your Penzle account. To access content from multiple projects, you must create separate API keys for each project.

Note

For security reasons, it is recommended that you use a secure way of storing your API keys, such as an environment variable, and not include them directly in your code. This will ensure that your API keys are not exposed if your code is published or shared.

Obtaining an API Token

To obtain an API key, you need to sign in to the Penzle web app and create a new API token from the API tokens section. You can create as many API keys as you need, and you can manage and revoke them at any time.

To manage API tokens, perform the following steps:

  1. Go to Development > Projects to display the Projects screen.
  2. Select the Project you want to manage.
  3. The Project details screen appears.
  4. Select the API Tokens section.
  5. Token edit screen.
    Penzle API token screen.
Note

If you plan to use multiple environments, you must make sure that the API keys that you already have are accessible by your other environments.

Token environments for a single project.

2. OAuth2 authentication

API for acquiring an OAuth token directly for a user account is a type of API that allows OAuth applications to acquire OAuth tokens for a user's account directly, without the need for user interaction. This type of API is often used when an OAuth application needs to perform actions on behalf of a user, such as accessing their content or data, and requires their permission to do so.

Once the user has logged in, the OAuth application will then make a request to the API to obtain an OAuth token.

In response to this request, the API will return an OAuth token that can be used to access the user's account. The OAuth token will typically include information about the user and the scopes of access granted to the OAuth application. The OAuth application can then use this token to make requests to the API on behalf of the user. API helps to ensure that user data and content is protected and only accessible with the user's permission.