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.

POST/api/backend/v1/end_user_api_keys/validate

Validate API Key

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

Properties

Name
apiKey *
Type
string
Description
The API key to validate

Request

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

Successful Response

{
    metadata: {
        "customKey": "customValue"
    },

    // This is only included if the API key is associated with a user
    user: {
        userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
        email: "test@example.com",
        // ...
    },

    // This is only included if the API key is associated with an organization
    org: {
        orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        orgName: "Example Organization",
        // ...
    },

    // This is only included if the API key is associated 
    // with BOTH a user and an organization
    userInOrg: {
        userAssignedRole: "Guest",
        userPermissions: ["CanReadProjectList"],
        // ...
    }
}

POST/api/backend/v1/end_user_api_keys/validate

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.

Properties

Name
apiKey *
Type
string
Description
The API key to validate

Request

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

Successful Response

{
    metadata: {
        "customKey": "customValue"
    },

    user: {
        userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
        email: "test@example.com",
        // ...
    },
}

POST/api/backend/v1/end_user_api_keys/validate

A convenience function that both validates an API key and makes sure it is assigned to an organization. It may be assigned to a user within that organization, but it must be associated with an organization.

Properties

Name
apiKey *
Type
string
Description
The API key to validate

Request

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

Successful Response

{
    metadata: {
        "customKey": "customValue"
    },

    org: {
        orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
        orgName: "Example Organization",
        // ...
    },


    // These two fields are only included if the API key is also associated with a user
    user: {
        userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
        email: "test@example.com",
        // ...
    },
    userInOrg: {
        userAssignedRole: "Guest",
        userPermissions: ["CanReadProjectList"],
        // ...
    }
}

POST/api/backend/v1/end_user_api_keys

Create API Key

Creates a new API key. This API key can be associated with a user, an organization, or no one. If it's associated with a user, the user's information will be returned on validation. It will also invalidated if the user is blocked/deleted. If it's associated with an organization, the organization's information will be returned on validation. It will also invalidated if the organization is deleted. You can associate it with both a user and an organization, in which case both will be returned on validation, including the role and permissions of the user within the organization. Finally, you can associate it with no one, in which case it will only be returned on validation if the API key is valid. In this case, the API key will not be invalidated if the user or organization is deleted. For any API key, you can attach metadata, which will be returned on validation as well.

Properties

Name
orgId
Type
string
Description
The ID of the organization to associate the API key with. If not provided, the API key will not be associated with an organization.
Name
userId
Type
string
Description
The ID of the user to associate the API key with. If not provided, the API key will not be associated with a user.
Name
expiresAtSeconds
Type
number
Description
A unix timestamp of when the API key should expire. If not provided, the API key will not expire.
Name
metadata
Type
{ [key: string]: any }
Description
Metadata to attach to the API key. This will be returned on validation.

Request

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

Successful Response

{
    apiKeyId: "justAnId",
    apiKeyToken: "dhopw42...",
}

PATCH/api/backend/v1/end_user_api_keys/<apiKeyId>

Update API Key

Updates an API Key. You can update the metadata or expiration, but you cannot change ownership.

Properties

Name
apiKeyId *
Type
string
Description
The ID of the API key to update. This is NOT the full API key, just the ID.
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. This will be returned on validation.

Request

auth.updateApiKey(
    "justAnId",
    {
        expiresAtSeconds: 1630425600,
        metadata: {
            customKey: "customValue",
        },
    },
)

Successful Response

{}

DELETE/api/backend/v1/end_user_api_keys/<apiKeyId>

Delete API Key

Deletes an API Key. You probably know this already, but after deleting an API Key, it will no longer be valid.

Properties

Name
apiKeyId *
Type
string
Description
The ID of the API key to update. This is NOT the full API key, just the ID.

Request

auth.deleteApiKey(
    "justAnId"
)

Successful Response

{}

GET/api/backend/v1/end_user_api_keys/<apiKeyId>

Fetch API Key

Fetches an API Key by it's ID. This will not return the full API key, just the metadata, expiration, and ownership.

Properties

Name
apiKeyId *
Type
string
Description
The ID of the API key to update. This is NOT the full API key, just the ID.

Request

auth.fetchApiKey(
    "justAnId"
)

Successful Response

{
    apiKeyId: "justAnId",
    createdAt: 1630425600,
    expiresAtSeconds: 1640425600,
    metadata: {
        "customKey": "customValue",
    },
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
}

GET/api/backend/v1/end_user_api_keys

Fetch Active API Keys

Fetches a list of active API Keys. This will not return the full API key, just the metadata, expiration, and ownership.

Properties

Name
userId
Type
string
Description
Filter by the user ID of the API key owner.
Name
userEmail
Type
string
Description
Filter by the email of the API key owner.
Name
orgId
Type
string
Description
Filter by the organization ID of the API key owner.
Name
pageSize
Type
number
Description
The number of results to return per page.
Name
pageNumber
Type
number
Description
The page number to return.

Request

auth.fetchCurrentApiKeys({
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    userEmail: "test@example.com",
    pageSize: 10,
    pageNumber: 0,
})

Successful Response

{
    apiKeys: [{
        apiKeyId: "justAnId",
        createdAt: 1630425600,
        expiresAtSeconds: 1640425600,
        metadata: {
            "customKey": "customValue",
        },
        userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
        orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    }],
    totalApiKeys: 1,
    currentPage: 0,
    pageSize: 10,
    hasMoreResults: false,
}

GET/api/backend/v1/end_user_api_keys/archived

Fetch Expired API Keys

Fetches a list of expired API Keys. This will not return the full API key, just the metadata, expiration, and ownership.

Properties

Name
userId
Type
string
Description
Filter by the user ID of the API key owner.
Name
userEmail
Type
string
Description
Filter by the email of the API key owner.
Name
orgId
Type
string
Description
Filter by the organization ID of the API key owner.
Name
pageSize
Type
number
Description
The number of results to return per page.
Name
pageNumber
Type
number
Description
The page number to return.

Request

auth.fetchArchivedApiKeys({
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    userEmail: "test@example.com",
    pageSize: 10,
    pageNumber: 0,
})

Successful Response

{
    apiKeys: [{
        apiKeyId: "justAnId",
        createdAt: 1630425600,
        expiresAtSeconds: 1640425600,
        metadata: {
            "customKey": "customValue",
        },
        userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
        orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    }],
    totalApiKeys: 1,
    currentPage: 0,
    pageSize: 10,
    hasMoreResults: false,
}