> ## Documentation Index
> Fetch the complete documentation index at: https://mako-docs.devinagiffy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve Platform User

> Resolve a platform user to an Hitler user (service-to-service)

## Overview

Resolves a platform user (Slack, Teams, WhatsApp) to an Hitler user and returns user information along with a short-lived JWT token for authenticated requests.

<Warning>
  This endpoint is for service-to-service communication only. It requires an API key and should
  never be called from client applications.
</Warning>

## Authentication

This endpoint uses API key authentication.

```bash theme={null}
X-API-Key: your-api-key
```

## Request Body

<ParamField body="platform" type="string" required>
  The platform identifier. One of: `slack`, `teams`, `whatsapp`
</ParamField>

<ParamField body="platformUserId" type="string" required>
  The user's ID on the platform (e.g., Slack user ID like `U0123456789`)
</ParamField>

<ParamField body="platformTeamId" type="string">
  The team/workspace ID on the platform (e.g., Slack workspace ID)
</ParamField>

## Response

<ResponseField name="userId" type="string">
  The Hitler user ID (UUID)
</ResponseField>

<ResponseField name="organizationId" type="string">
  The organization ID (UUID)
</ResponseField>

<ResponseField name="email" type="string">
  The user's email address
</ResponseField>

<ResponseField name="name" type="string">
  The user's display name
</ResponseField>

<ResponseField name="role" type="string">
  The user's role: `employee`, `manager`, or `admin`
</ResponseField>

<ResponseField name="token" type="string">
  A short-lived JWT token (15 minutes) for making authenticated requests on behalf of the user
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.hitler.io/api/users/resolve-platform \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-api-key" \
    -d '{
      "platform": "slack",
      "platformUserId": "U0123456789",
      "platformTeamId": "T0123456789"
    }'
  ```

  ```typescript SDK theme={null}
  const client = new HitlerClient({
    baseUrl: "https://api.hitler.io",
    apiKey: "your-api-key",
  });

  const resolved = await client.resolveUser({
    platform: "slack",
    platformUserId: "U0123456789",
    platformTeamId: "T0123456789",
  });

  if (resolved) {
    console.log(`User: ${resolved.name}`);
    client.setUserToken(resolved.token);
    // Now make authenticated requests on behalf of the user
  }
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "660e8400-e29b-41d4-a716-446655440001",
  "email": "john@company.com",
  "name": "John Smith",
  "role": "employee",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### User Not Found

If the platform identity is not linked to any user, the endpoint returns `null` with a 200 status code.

```json theme={null}
null
```

## Usage Notes

### Token Lifecycle

The returned token has a 15-minute expiration. Bot services should:

1. Cache the token with its expiry time
2. Re-resolve the user when the token expires
3. Use the token for all API calls on behalf of the user

### Security Considerations

* Never expose the API key to clients
* The returned token should only be used server-side
* Consider implementing additional rate limiting for this endpoint
* Monitor for unusual resolution patterns that could indicate abuse

### Platform Identity Linking

Users must have their platform identity linked before they can be resolved. This is done through:

1. OAuth flow (automatic linking during Slack/Teams login)
2. Admin portal (manual linking by organization admins)
3. API call to `POST /api/users/:id/identities`