User API keys

Create and manage personal API keys for programmatic access.

API keys let a user authenticate to the Hailer API without a username and password, which is the recommended way to call the API from scripts, integrations, and agents. A key belongs to a single user and carries that user's permissions. Create a key with v3.userApiKey.create (the secret is returned once, at creation, and cannot be retrieved again), then pass it when constructing the @hailer/cli client. Keys can be scoped to specific IP addresses and revoked at any time.

Endpoints

Endpoint	Arguments	Returns
v3.user.apikey.create	name: string, workspaceId: string, whitelistIps: string[], delegatedToUrl?: string	object
v3.user.apikey.list	none	object[]
v3.user.apikey.remove	apiKeyId: string	boolean
v3.user.apikey.update	apiKeyId: string, name: string, whitelistIps: string[]	boolean

v3.user.apikey.create

Description

Create a Hailer API key tied to a workspace, optionally IP-restricted. Key shown only once at creation.

Parameters

Argument 1 (string, required):

Argument 2 (string, required):

Argument 3 (string[], required):

Argument 4 (string, optional):

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.user.apikey.create', [
  'string', // argument 1 (required)
  'string', // argument 2 (required)
  ['string'],
  'string', // argument 4
]);
console.log(result);

Returns

Field	Type	Required	Description
_id	string	yes
key	string	yes

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.user.apikey.list

Description

List all active API keys for the authenticated user. Returns key metadata, does not return the actual key secret.

Parameters

Undocumented

This endpoint declares no argument schema in the source yet.

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.user.apikey.list', []);
console.log(result);

Returns

Array of objects:

Field	Type	Required	Description
_id	string	yes
uid	string	yes
workspaceId	string	yes
name	string	yes
keyPrefix	string	yes
whitelistIps	string[]	yes
created	number	yes
updated	number	no
expires	number	yes
lastUsed	number	no
delegatedToUrl	string	no

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.user.apikey.remove

Description

Remove a user API key. The key will no longer be usable for authentication. Only the owner of the API key can remove it.

Parameters

Argument 1 (string, required):

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.user.apikey.remove', [
  'string', // argument 1 (required)
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.

v3.user.apikey.update

Description

Update an existing user API key. Allows changing the name and IP whitelist restrictions.

Parameters

Argument 1 (string, required):

Argument 2 (string, required):

Argument 3 (string[], required):

Example

const { Client } = require('@hailer/cli');

const client = await Client.create({
  host: 'https://api.hailer.com',
  username: 'you@example.com',
  password: '••••••',
});

const result = await client.request('v3.user.apikey.update', [
  'string', // argument 1 (required)
  'string', // argument 2 (required)
  ['string'],
]);
console.log(result);

Returns

boolean

Auth: requires an authenticated session.

Errors: on failure returns the standard Hailer error object { code, msg, details?, debug? }.