ApiKeyService

Este conteúdo não está disponível em sua língua ainda.

Manages scoped API keys for programmatic access to the Pidgr API (MCP agents, service integrations, SCIM provisioning). Keys are scoped to an organization and carry an explicit set of permissions.

Methods

Method	Description
`CreateApiKey`	Create a new scoped API key
`ListApiKeys`	List all API keys for the organization
`RevokeApiKey`	Revoke an existing API key

CreateApiKey

Create a new API key with an explicit permission set and optional expiry. The full key value is only returned once — store it securely.

Keys created by a caller authenticated with an API key (rather than a user session) record no user creator.

Authorization: Requires PERMISSION_ORG_WRITE permission

Request: `CreateApiKeyRequest`

Field	Type	Description
`name`	`string`	Human-friendly label for the key. Required, max 200 characters.
`permissions`	`Permission[]`	Permissions to grant. Required, at least one. `PERMISSION_UNSPECIFIED` values are rejected.
`expires_at`	`Timestamp`	Optional expiration time. If omitted, the key does not expire.
`key_type`	`KeyType`	Type of key to create. Defaults to `KEY_TYPE_API_KEY`. SCIM tokens use the `pidgr_scim_` prefix instead of `pidgr_k_`.

Response: `CreateApiKeyResponse`

Field	Type	Description
`api_key`	`ApiKey`	The created API key metadata.
`key`	`string`	The full secret key value (e.g. `pidgr_k_abc12345...`). Only returned on creation — not retrievable later.

Example

TypeScript (Connect-Web)

const response = await apiKeyClient.createApiKey({
  name: "CI Integration",
  permissions: [Permission.CAMPAIGNS_READ, Permission.CAMPAIGNS_WRITE],
});
// Store response.key securely — it won't be shown again

Go (gRPC)

resp, err := apiKeyClient.CreateApiKey(ctx, &pidgrv1.CreateApiKeyRequest{
    Name: "CI Integration",
    Permissions: []pidgrv1.Permission{
        pidgrv1.Permission_PERMISSION_CAMPAIGNS_READ,
        pidgrv1.Permission_PERMISSION_CAMPAIGNS_WRITE,
    },
})
// Store resp.Key securely — it won't be shown again

ListApiKeys

List all active (non-revoked) API keys for the organization. Full key values are never included.

Authorization: Requires PERMISSION_ORG_READ permission

Request: `ListApiKeysRequest`

Field	Type	Description
`key_type`	`KeyType`	Optional filter by key type. Unspecified returns all keys.

Response: `ListApiKeysResponse`

Field	Type	Description
`api_keys`	`ApiKey[]`	All active API keys (metadata only, no secrets).

RevokeApiKey

Revoke an API key. The key becomes immediately unusable.

Authorization: Requires PERMISSION_ORG_WRITE permission

Request: `RevokeApiKeyRequest`

Field	Type	Description
`api_key_id`	`string`	ID of the API key to revoke. Required.

Response: `RevokeApiKeyResponse`

Empty response on success.

ApiKey Message

Field	Type	Description
`id`	`string`	Unique identifier.
`name`	`string`	Human-friendly label (e.g. “MCP Production”, “CI Pipeline”).
`key_prefix`	`string`	Displayable prefix of the key (e.g. `pidgr_k_abc12345`). Used for identification — the full key is only returned on creation.
`permissions`	`Permission[]`	Permissions granted to this key.
`created_at`	`Timestamp`	When the key was created.
`last_used_at`	`Timestamp`	Last time the key was used to authenticate a request. Empty if never used.
`expires_at`	`Timestamp`	When the key expires. Empty means no expiration.
`key_type`	`KeyType`	Type of this key. Defaults to `KEY_TYPE_API_KEY` for existing keys.

Enums

KeyType

Value	Description
`KEY_TYPE_API_KEY`	Standard API key (`pidgr_k_` prefix)
`KEY_TYPE_SCIM_TOKEN`	SCIM provisioning token (`pidgr_scim_` prefix)