feat: Add user API key methods (#1655)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: ethinallen

src/user-management/fixtures/create-user-api-key.json

@@ -0,0 +1,17 @@
+{
+  "object": "api_key",
+  "id": "api_key_01EHZNVPK3SFK441A1RGBFSHRT",
+  "owner": {
+    "type": "user",
+    "id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
+    "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT"
+  },
+  "name": "Production API Key",
+  "obfuscated_value": "sk_...3456",
+  "last_used_at": null,
+  "expires_at": "2030-01-01T00:00:00.000Z",
+  "permissions": ["posts:read", "posts:write"],
+  "created_at": "2026-01-15T12:00:00.000Z",
+  "updated_at": "2026-01-15T12:00:00.000Z",
+  "value": "test_api_key_value"
+}

src/user-management/fixtures/list-user-api-keys.json

@@ -0,0 +1,24 @@
+{
+  "data": [
+    {
+      "object": "api_key",
+      "id": "api_key_01EHZNVPK3SFK441A1RGBFSHRT",
+      "owner": {
+        "type": "user",
+        "id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
+        "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT"
+      },
+      "name": "Production API Key",
+      "obfuscated_value": "sk_...3456",
+      "last_used_at": null,
+      "expires_at": null,
+      "permissions": ["posts:read", "posts:write"],
+      "created_at": "2026-01-15T12:00:00.000Z",
+      "updated_at": "2026-01-15T12:00:00.000Z"
+    }
+  ],
+  "list_metadata": {
+    "before": null,
+    "after": null
+  }
+}

src/user-management/interfaces/create-user-api-key-options.interface.ts

@@ -0,0 +1,21 @@
+import { PostOptions } from '../../common/interfaces';
+
+export interface CreateUserApiKeyOptions {
+  name: string;
+  organizationId: string;
+  permissions?: string[];
+  expiresAt?: Date;
+}
+
+export interface SerializedCreateUserApiKeyOptions {
+  name: string;
+  organization_id: string;
+  permissions?: string[];
+  expires_at?: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface CreateUserApiKeyRequestOptions extends Pick<
+  PostOptions,
+  'idempotencyKey'
+> {}

src/user-management/interfaces/index.ts

@@ -19,6 +19,7 @@ export * from './authorization-url-options.interface';
 export * from './create-magic-auth-options.interface';
 export * from './create-organization-membership-options.interface';
 export * from './create-password-reset-options.interface';
+export * from './create-user-api-key-options.interface';
 export * from './create-user-options.interface';
 export * from './email-verification.interface';
 export * from './enroll-auth-factor.interface';
@@ -31,6 +32,7 @@ export * from './list-invitations-options.interface';
 export * from './list-organization-memberships-options.interface';
 export * from './list-sessions-options.interface';
 export * from './list-user-feature-flags-options.interface';
+export * from './list-user-api-keys-options.interface';
 export * from './list-users-options.interface';
 export * from './locale.interface';
 export * from './logout-url-options.interface';
@@ -50,4 +52,6 @@ export * from './update-organization-membership-options.interface';
 export * from './update-user-options.interface';
 export * from './update-user-password-options.interface';
 export * from './user.interface';
+export * from './user-api-key.interface';
+export * from './user-api-key-with-value.interface';
 export * from './verify-email-options.interface';

src/user-management/interfaces/list-user-api-keys-options.interface.ts

@@ -0,0 +1,9 @@
+import { PaginationOptions } from '../../common/interfaces/pagination-options.interface';
+
+export interface ListUserApiKeysOptions extends PaginationOptions {
+  organizationId?: string;
+}
+
+export interface SerializedListUserApiKeysOptions extends PaginationOptions {
+  organization_id?: string;
+}

src/user-management/interfaces/user-api-key-with-value.interface.ts

@@ -0,0 +1,9 @@
+import { SerializedUserApiKey, UserApiKey } from './user-api-key.interface';
+
+export interface UserApiKeyWithValue extends UserApiKey {
+  value: string;
+}
+
+export interface SerializedUserApiKeyWithValue extends SerializedUserApiKey {
+  value: string;
+}

src/user-management/interfaces/user-api-key.interface.ts

@@ -0,0 +1,33 @@
+export interface UserApiKey {
+  object: 'api_key';
+  id: string;
+  owner: {
+    type: 'user';
+    id: string;
+    organizationId: string;
+  };
+  name: string;
+  obfuscatedValue: string;
+  lastUsedAt: string | null;
+  expiresAt: string | null;
+  permissions: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SerializedUserApiKey {
+  object: 'api_key';
+  id: string;
+  owner: {
+    type: 'user';
+    id: string;
+    organization_id: string;
+  };
+  name: string;
+  obfuscated_value: string;
+  last_used_at: string | null;
+  expires_at: string | null;
+  permissions: string[];
+  created_at: string;
+  updated_at: string;
+}

src/user-management/serializers/create-user-api-key-options.serializer.ts

@@ -0,0 +1,15 @@
+import {
+  CreateUserApiKeyOptions,
+  SerializedCreateUserApiKeyOptions,
+} from '../interfaces/create-user-api-key-options.interface';
+
+export function serializeCreateUserApiKeyOptions(
+  options: CreateUserApiKeyOptions,
+): SerializedCreateUserApiKeyOptions {
+  return {
+    name: options.name,
+    organization_id: options.organizationId,
+    permissions: options.permissions,
+    expires_at: options.expiresAt?.toISOString(),
+  };
+}

src/user-management/serializers/index.ts

@@ -12,10 +12,12 @@ export * from './authentication-factor.serializer';
 export * from './authentication-response.serializer';
 export * from './create-magic-auth-options.serializer';
 export * from './create-password-reset-options.serializer';
+export * from './create-user-api-key-options.serializer';
 export * from './email-verification.serializer';
 export * from './enroll-auth-factor-options.serializer';
 export * from './invitation.serializer';
 export * from './list-sessions-options.serializer';
+export * from './list-user-api-keys-options.serializer';
 export * from './magic-auth.serializer';
 export * from './password-reset.serializer';
 export * from './reset-password-options.serializer';
@@ -25,3 +27,5 @@ export * from './send-radar-sms-challenge-options.serializer';
 export * from './update-user-options.serializer';
 export * from './update-user-password-options.serializer';
 export * from './user.serializer';
+export * from './user-api-key.serializer';
+export * from './user-api-key-with-value.serializer';

src/user-management/serializers/list-user-api-keys-options.serializer.ts

@@ -0,0 +1,16 @@
+import {
+  ListUserApiKeysOptions,
+  SerializedListUserApiKeysOptions,
+} from '../interfaces/list-user-api-keys-options.interface';
+
+export function serializeListUserApiKeysOptions(
+  options: ListUserApiKeysOptions,
+): SerializedListUserApiKeysOptions {
+  return {
+    limit: options.limit,
+    before: options.before,
+    after: options.after,
+    order: options.order,
+    organization_id: options.organizationId,
+  };
+}