API Key Reference

These APIs can be called from the backend using your PropelAuth API Key. These APIs are used to validate, create, and delete API Keys for your users - which are separate from your PropelAuth API Key.

These can also be referred to as M2M (Machine to Machine) Keys or Service Accounts.

Validate API Key

Validates an API key and returns any associated user or organization. This also returns any metadata attached to the API key.

Required Permissions

Validate End-user API Keys

Properties

• Name apiKey *Type string Description The API key to validate

Request

auth.validateApiKey(
    "dhopw42...",
)

Successful Response

{
    "metadata": {
        "customKey": "customValue"
    },
    "user": {
        "user_id": "31c41c16-c281-44ae-9602-8a047e3bf33d",
        "email": "test@example.com"
    },
    "org": {
        "org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        "org_name": "Example Organization"
    },
    "user_in_org": {
        "userAssignedRole": "Guest",
        "userPermissions": ["CanReadProjectList"]
    }
}

Validate Personal API Key

A convenience function that both validates an API key and makes sure it is assigned to a user, not an organization.

Required Permissions

Validate End-user API Keys

Properties

• Name apiKey *Type string Description The API key to validate

Request

auth.validatePersonalApiKey(
    "dhopw42...",
)

Successful Response

{
    "metadata": {
        "customKey": "customValue"
    },
    "user": {
        "user_id": "31c41c16-c281-44ae-9602-8a047e3bf33d",
        "email": "test@example.com"
    }
}

Validate Org API Key

A convenience function that both validates an API key and makes sure it is assigned to an organization.

Required Permissions

Validate End-user API Keys

Properties

• Name apiKey *Type string Description The API key to validate

Request

auth.validateOrgApiKey(
    "dhopw42...",
)

Successful Response

{
    "metadata": {
        "customKey": "customValue"
    },
    "org": {
        "org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        "org_name": "Example Organization"
    },
    "user": {
        "user_id": "31c41c16-c281-44ae-9602-8a047e3bf33d",
        "email": "test@example.com"
    },
    "user_in_org": {
        "userAssignedRole": "Guest",
        "userPermissions": ["CanReadProjectList"]
    }
}

Create API Key

Creates a new API key. This API key can be associated with a user, an organization, or no one.

Required Permissions

Create End-user API Keys

Properties

• Name orgId Type string Description The ID of the organization to associate the API key with.
• Name userId Type string Description The ID of the user to associate the API key with.
• Name expiresAtSeconds Type number Description A unix timestamp of when the API key should expire.
• Name metadata Type { [key: string]: any } Description Metadata to attach to the API key.
• Name displayName Type string Description A human-readable name for the API key.

Request

auth.createApiKey({
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    expiresAtSeconds: 1630425600,
    metadata: {
        customKey: "customValue",
    },
    displayName: "My API Key",
})

Successful Response

{
    "api_key_id": "justAnId",
    "api_key_token": "dhopw42..."
}

Fetch API Key Usage

Fetches the amount of times an API key was validated on a certain date.

Required Permissions

Read User Insights Data

Properties

• Name apiKeyId Type string Description The ID of the API key.
• Name userId Type string Description The ID of the user.
• Name orgId Type string Description The ID of the organization.
• Name date *Type string Description The date to filter by. Must be in YYYY-MM-DD format.

Request

auth.fetchApiKeyUsage({
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    api_key_id: "dhopw42...",
    date: "2025-01-30",
})

Successful Response

{
    "count": 2
}