Skip to main content
POST
Resolve Platform User

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.
This endpoint is for service-to-service communication only. It requires an API key and should never be called from client applications.

Authentication

This endpoint uses API key authentication.

Request Body

string
required
The platform identifier. One of: slack, teams, whatsapp
string
required
The user’s ID on the platform (e.g., Slack user ID like U0123456789)
string
The team/workspace ID on the platform (e.g., Slack workspace ID)

Response

string
The Hitler user ID (UUID)
string
The organization ID (UUID)
string
The user’s email address
string
The user’s display name
string
The user’s role: employee, manager, or admin
string
A short-lived JWT token (15 minutes) for making authenticated requests on behalf of the user

Example

Success Response

User Not Found

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

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