Scoped API Keys and OAuth Clients

Pentographer provides two authentication methods for developers and automated clients: Scoped API Keys (best for simple scripts and Model Context Protocol connections) and OAuth Clients (best for machine-to-machine integrations). To see how to use Scoped API keys to connect desktop AI editors, see the MCP Server Setup guide.

Scoped API Keys

API keys authenticate requests directly using a static secret.

Creating an API Key

To create a new API key:

1. Navigate to Workspace Settings > API Keys (or /settings).
2. Click New key.
3. Name your key and click Save.
4. Copy the key from the confirmation dialog. The system displays this key only once.

All Pentographer API keys begin with the ptg_ prefix.

Key Access and Revocation

• Visibility: Administrators and Owners can view and manage all API keys created within the organization. Regular organization members can view and manage only their own keys.
• Revocation: Click Revoke on any active key to delete it. The system immediately rejects subsequent requests using that key with a 401 Unauthorized status.

OAuth Clients

OAuth clients provide a robust, temporary session-based authentication flow using client credentials.

Creating an OAuth Client

To register a client application:

1. Navigate to Workspace Settings > OAuth Clients (or /settings).
2. Click New client.
3. Enter a name for your client and click Save.
4. Copy the generated Client ID (prefixed with ptgc_) and Client Secret (prefixed with ptgs_). Pentographer displays the secret only once.

Requesting an Access Token

To retrieve a temporary Bearer token, send a POST request to /api/oauth/token with the client credentials:

curl -X POST https://app.pentographer.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=ptgc_your_client_id" \
  -d "client_secret=ptgs_your_client_secret"

[!NOTE] If you are self-hosting, replace https://app.pentographer.com with your own deployment URL.

A successful request returns a JSON object containing the access_token, the token_type (set to Bearer), and the expiration lifetime (such as expires_in: 3600 seconds):

{
  "access_token": "your_temporary_jwt_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Authenticating Requests

To query the GraphQL API or interact with system endpoints, include the access token or static API key in your request header:

Authorization: Bearer <your_access_token_or_ptg_key>

For instructions on constructing queries and using the query explorer, read the GraphQL API Reference.