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

Validate Org API Key

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