# 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](https://docs.propelauth.com/reference/api/apikey#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

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

### Successful Response

```json
{
    "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](https://docs.propelauth.com/reference/api/apikey#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

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

### Successful Response

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

---

## [Validate Org API Key](https://docs.propelauth.com/reference/api/apikey#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

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

### Successful Response

```json
{
    "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](https://docs.propelauth.com/reference/api/apikey#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

```javascript
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

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

---

## [Fetch API Key Usage](https://docs.propelauth.com/reference/api/apikey#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

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

### Successful Response

```json
{
    "count": 2
}
```