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 supported on a growing set of scopes:

Feature flag local evaluation and remote config (feature_flag:read scope)
Endpoints execution (endpoint:read scope)
Support external tickets API reads (support_ticket:read scope)

Migrating from the feature flags secure API key

Project secret API keys replace the legacy feature flags secure API key. If you're currently using one, we'll migrate it to a project secret API key without impacting your application.

How to obtain a project secret API key

Go to the Project secret API keys section in your project settings.
Click Create project secret API key.
Give your key a label to describe its purpose.
Choose the scopes for your key. We recommend selecting only the scopes the service really needs. This is a security best practice.
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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/project_secret_api_keys/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/project_secret_api_keys/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"label": "string",
		"scopes": "array"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/project_secret_api_keys/{project_secret_api_key_id}/".format(
        project_id=project_id,
		project_secret_api_key_id="<the project secret api key id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/project_secret_api_keys/{project_secret_api_key_id}/".format(
        project_id=project_id,
		project_secret_api_key_id="<the project secret api key id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"label": "string"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/project_secret_api_keys/{project_secret_api_key_id}/".format(
        project_id=project_id,
		project_secret_api_key_id="<the project secret api key id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/project_secret_api_keys/{project_secret_api_key_id}/roll/".format(
        project_id=project_id,
		project_secret_api_key_id="<the project secret api key id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
  ]
}