Project Secret Api

For instructions on how to authenticate to use this endpoint, see API overview.

Project secret API keys are server-to-server credentials scoped to a single project. They're the right choice when a backend service needs scoped, project-level access without being tied to anyone's user account.

Unlike a personal API key, a project secret API key doesn't represent a user—it isn't affected when a teammate leaves, and it only has the scopes you grant it.

Today, they're only supported on a small set of scopes, with more products on the way:

  • Endpoints execution (endpoint:read scope)
Migrating from the team secret token

Project secret API keys will replace the legacy per-team secret token. If you're currently using a team secret token, we'll migrate it to a project secret API key without impacting your application.

How to obtain a project secret API key

  1. Go to the Project secret API keys section in your project settings.
  2. Click Create project secret API key.
  3. Give your key a label to describe its purpose.
  4. Choose the scopes for your key. We recommend selecting only the scopes the service really needs. This is a security best practice.
  5. Immediately copy the key's value, as you'll never see it again after refreshing the page.

How to authenticate using the project secret API key

Pass the key in the Authorization header using Bearer authentication:

JavaScript
const headers = {
  Authorization: `Bearer ${POSTHOG_PROJECT_SECRET_API_KEY}`,
}

PostHog detects the kind of key you sent from its phs_ prefix and authenticates accordingly.

Endpoints

GET
POST
GET
PATCH
DELETE
POST

List all project secret api keys

Required API key scopes

project:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/project_secret_api_keys
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/project_secret_api_keys/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "string",
      "label": "string",
      "value": "string",
      "mask_value": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "last_used_at": "2019-08-24T14:15:22Z",
      "last_rolled_at": "2019-08-24T14:15:22Z",
      "scopes": [
        "string"
      ]
    }
  ]
}

Create project secret api keys

Required API key scopes

project:write

Request parameters

  • label
    string
  • scopes
    array

Response


Example request

POST /api/projects/:project_id/project_secret_api_keys
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/project_secret_api_keys/\
	-d label="string",\
	-d scopes="array"

Example response

Status 201
RESPONSE
{
  "id": "string",
  "label": "string",
  "value": "string",
  "mask_value": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "last_used_at": "2019-08-24T14:15:22Z",
  "last_rolled_at": "2019-08-24T14:15:22Z",
  "scopes": [
    "string"
  ]
}

Retrieve project secret api keys

Required API key scopes

project:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/project_secret_api_keys/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/project_secret_api_keys/:id/

Example response

Status 200
RESPONSE
{
  "id": "string",
  "label": "string",
  "value": "string",
  "mask_value": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "last_used_at": "2019-08-24T14:15:22Z",
  "last_rolled_at": "2019-08-24T14:15:22Z",
  "scopes": [
    "string"
  ]
}

Update project secret api keys

Required API key scopes

project:write

Path parameters

  • id
    string

Request parameters

  • label
    string
  • scopes
    array

Response


Example request

PATCH /api/projects/:project_id/project_secret_api_keys/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/project_secret_api_keys/:id/\
	-d label="string"

Example response

Status 200
RESPONSE
{
  "id": "string",
  "label": "string",
  "value": "string",
  "mask_value": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "last_used_at": "2019-08-24T14:15:22Z",
  "last_rolled_at": "2019-08-24T14:15:22Z",
  "scopes": [
    "string"
  ]
}

Delete project secret api keys

Required API key scopes

project:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/project_secret_api_keys/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/project_secret_api_keys/:id/

Example response

Status 204 No response body

Create project secret api keys roll

Roll a project secret API key

Required API key scopes

project:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/project_secret_api_keys/:id/roll
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/project_secret_api_keys/:id/roll/

Example response

Status 200
RESPONSE
{
  "id": "string",
  "label": "string",
  "value": "string",
  "mask_value": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "last_used_at": "2019-08-24T14:15:22Z",
  "last_rolled_at": "2019-08-24T14:15:22Z",
  "scopes": [
    "string"
  ]
}

Community questions