Introspect active API credentials, verify assigned permission scopes, and check account tier details.
Quick Reference#
| Endpoint | Method | Required Scope | Description |
|---|---|---|---|
/v1/me | GET | None (afp_...) | Introspect caller identity, assigned permission scopes, role, and subscription tier. |
/v1/auth/whoami | GET | None (afp_...) | Gateway introspection alias for reverse proxies and middleware. |
Introspect Caller Identity#
GET /v1/me
Retrieves the authenticated principal's user account details, active subscription tier, and assigned permission scopes. Useful for application startup checks, CLI handshakes, and credential verification.
Scope: None (Any active key)Rate Limit: 60 req/minIdempotent: Yes
Request Headers#
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Optional* | Bearer afp_... |
x-api-key | string | Optional* | afp_... (*Provide either Authorization or x-api-key). |
Accept | string | Yes | application/json |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/me" \ -H "Authorization: Bearer afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "user_id": "d3b07384-d113-4674-bc50-a88981298418", "email": "developer@company.com", "full_name": "Alex Mercer", "role": "user", "tier": "business", "created_at": "2026-09-04T12:00:00.000Z", "auth_type": "api_key", "scopes": [ "aliases:read", "aliases:write", "domains:read", "destinations:read", "categories:read", "analytics:read" ]}Response Fields#
| Field | Type | Description |
|---|---|---|
user_id | string | Unique RFC 4122 UUID of the authenticated account principal. |
email | string | Primary login email address associated with the account. |
full_name | string | null | Display name of the account user. |
role | string | Security role assigned to the user ("user" or "admin"). |
tier | string | Current subscription tier ("free", "pro", "business"). |
created_at | string | ISO 8601 UTC timestamp indicating when the user profile was established. |
auth_type | string | Credential mechanism used for this request ("api_key", "session", or "extension"). |
scopes | array | List of authorized resource:action permission scopes granted to this credential. |
Error Responses#
| Status Code | Code | Error Message | Reason |
|---|---|---|---|
401 | MISSING_CREDENTIALS | "Unauthorized: Missing API Key or Session Token" | Neither Authorization nor x-api-key header was provided. |
401 | INVALID_API_KEY | "Unauthorized: Invalid API Key" | Key does not exist or SHA-256 hash failed verification. |
401 | INACTIVE_API_KEY | "Unauthorized: API Key is inactive" | Key has been paused or revoked by the user. |
401 | EXPIRED_API_KEY | "Unauthorized: API Key has expired" | Key exceeded its configured expiration date. |
403 | IP_NOT_ALLOWED | "Forbidden: IP not allowed for this token" | Calling IP address does not match key's IP allowlist restriction. |
429 | RATE_LIMIT_EXCEEDED | "Too Many Requests" | Key exceeded standard 60 req/min rate threshold. Check Retry-After. |
Gateway Introspection Alias#
GET /v1/auth/whoami
Standard RFC 7662 token introspection endpoint. Operates identically to GET /v1/me, provided for API gateway plugins (Kong, Envoy, Cloudflare Workers) and reverse proxies requiring a standard whoami route.
Scope: None (Any active key)Rate Limit: 60 req/minIdempotent: Yes
Request Headers#
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Optional* | Bearer afp_... |
x-api-key | string | Optional* | afp_... (*Provide either Authorization or x-api-key). |
Accept | string | Yes | application/json |
cURL Example#
Terminal
curl -X GET "https://api.aliasfleet.com/v1/auth/whoami" \ -H "x-api-key: afp_4a8f9c1b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e" \ -H "Accept: application/json"Response (200 OK)#
JSON
{ "user_id": "d3b07384-d113-4674-bc50-a88981298418", "email": "developer@company.com", "full_name": "Alex Mercer", "role": "user", "tier": "business", "created_at": "2026-09-04T12:00:00.000Z", "auth_type": "api_key", "scopes": [ "aliases:read", "aliases:write" ]}Response Fields#
See GET /v1/me above for complete field definitions.