Reference

BackstageClient.apiKeys

BackstageClient.apiKeys in @ticketlayer/backstage.

@ticketlayer/backstage / BackstageClient / apiKeys

apiKeys: {
  create: (request: {
     accountId?: string;
     expiresAt?: any;
     name: string;
     scopes: string[];
   }, requestOptions?: RequestOptions) => Promise<{
     apiKey: {
        accountId: string | null;
        createdAt: string;
        createdBy: string | null;
        expiresAt: string | null;
        id: string;
        keyPrefix: string;
        lastUsedAt: string | null;
        name: string;
        organisationId: string;
        previousKeyExpiresAt: string | null;
        revokedAt: string | null;
        rolledAt: string | null;
        scopes: string[];
     };
     key: string;
  }>;
  get: (id: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     createdAt: string;
     createdBy: string | null;
     expiresAt: string | null;
     id: string;
     keyPrefix: string;
     lastUsedAt: string | null;
     name: string;
     organisationId: string;
     previousKeyExpiresAt: string | null;
     revokedAt: string | null;
     rolledAt: string | null;
     scopes: string[];
  }>;
  list: (requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     createdAt: string;
     createdBy: string | null;
     expiresAt: string | null;
     id: string;
     keyPrefix: string;
     lastUsedAt: string | null;
     name: string;
     organisationId: string;
     previousKeyExpiresAt: string | null;
     revokedAt: string | null;
     rolledAt: string | null;
     scopes: string[];
  }[]>;
  listScopes: (requestOptions?: RequestOptions) => Promise<{
     description: string;
     label: string;
     scope: string;
  }[]>;
  revoke: (id: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     createdAt: string;
     createdBy: string | null;
     expiresAt: string | null;
     id: string;
     keyPrefix: string;
     lastUsedAt: string | null;
     name: string;
     organisationId: string;
     previousKeyExpiresAt: string | null;
     revokedAt: string | null;
     rolledAt: string | null;
     scopes: string[];
  }>;
  roll: (id: string, request: {
     graceSeconds?: number;
   }, requestOptions?: RequestOptions) => Promise<{
     apiKey: {
        accountId: string | null;
        createdAt: string;
        createdBy: string | null;
        expiresAt: string | null;
        id: string;
        keyPrefix: string;
        lastUsedAt: string | null;
        name: string;
        organisationId: string;
        previousKeyExpiresAt: string | null;
        revokedAt: string | null;
        rolledAt: string | null;
        scopes: string[];
     };
     key: string;
  }>;
  update: (id: string, request: {
     expiresAt?: any;
     name?: string;
     scopes?: string[];
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string | null;
     createdAt: string;
     createdBy: string | null;
     expiresAt: string | null;
     id: string;
     keyPrefix: string;
     lastUsedAt: string | null;
     name: string;
     organisationId: string;
     previousKeyExpiresAt: string | null;
     revokedAt: string | null;
     rolledAt: string | null;
     scopes: string[];
  }>;
};

Defined in: client.ts:1885

API Keys methods

create()#

create: (request: {
  accountId?: string;
  expiresAt?: any;
  name: string;
  scopes: string[];
}, requestOptions?: RequestOptions) => Promise<{
  apiKey: {
     accountId: string | null;
     createdAt: string;
     createdBy: string | null;
     expiresAt: string | null;
     id: string;
     keyPrefix: string;
     lastUsedAt: string | null;
     name: string;
     organisationId: string;
     previousKeyExpiresAt: string | null;
     revokedAt: string | null;
     rolledAt: string | null;
     scopes: string[];
  };
  key: string;
}>;

Create an organisation API key Creates a long-lived key a partner server uses to call this API and to mint embed sessions. The key material is in this response once. Users only, holding apikeys.create across the whole organisation. ledger.read needs the organisation to allow API keys to read its finance data first (allowApiKeyLedgerRead on the organisation): while it does not, a key with the scope is refused (403 API_KEY_LEDGER_READ_NOT_ALLOWED), and turning it off later stops existing keys reading the ledger.

Parameters#

Parameter	Type
`request`	{ `accountId?`: `string`; `expiresAt?`: `any`; `name`: `string`; `scopes`: `string`[]; }
`request.accountId?`	`string`
`request.expiresAt?`	`any`
`request.name?`	`string`
`request.scopes?`	`string`[]
`requestOptions?`	`RequestOptions`

Returns#

Promise<{ apiKey: { accountId: string | null; createdAt: string; createdBy: string | null; expiresAt: string | null; id: string; keyPrefix: string; lastUsedAt: string | null; name: string; organisationId: string; previousKeyExpiresAt: string | null; revokedAt: string | null; rolledAt: string | null; scopes: string[]; }; key: string; }>

Operation Id#

createApiKey

get()#

get: (id: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  createdAt: string;
  createdBy: string | null;
  expiresAt: string | null;
  id: string;
  keyPrefix: string;
  lastUsedAt: string | null;
  name: string;
  organisationId: string;
  previousKeyExpiresAt: string | null;
  revokedAt: string | null;
  rolledAt: string | null;
  scopes: string[];
}>;

Get an organisation API key One key of the organisation, revoked or not. Key material is never returned. Users only, holding apikeys.read across the whole organisation.

Parameters#

Parameter	Type
`id`	`string`
`requestOptions?`	`RequestOptions`

Returns#

Promise<{ accountId: string | null; createdAt: string; createdBy: string | null; expiresAt: string | null; id: string; keyPrefix: string; lastUsedAt: string | null; name: string; organisationId: string; previousKeyExpiresAt: string | null; revokedAt: string | null; rolledAt: string | null; scopes: string[]; }>

Operation Id#

getApiKey

list()#

list: (requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  createdAt: string;
  createdBy: string | null;
  expiresAt: string | null;
  id: string;
  keyPrefix: string;
  lastUsedAt: string | null;
  name: string;
  organisationId: string;
  previousKeyExpiresAt: string | null;
  revokedAt: string | null;
  rolledAt: string | null;
  scopes: string[];
}[]>;

List organisation API keys Lists every key of the organisation, revoked ones included. Key material is never returned. Users only, holding apikeys.read across the whole organisation.

Parameters#

Parameter	Type
`requestOptions?`	`RequestOptions`

Returns#

Operation Id#

listApiKeys

listScopes()#

listScopes: (requestOptions?: RequestOptions) => Promise<{
  description: string;
  label: string;
  scope: string;
}[]>;

List the scopes an organisation API key may hold Every scope a key may be created with or changed to, in the order the catalogue keeps them, each with a label and a description in the words the consent page uses. The list is exactly what POST and PATCH accept. Users only, holding apikeys.read across the whole organisation.

Parameters#

Parameter	Type
`requestOptions?`	`RequestOptions`

Returns#

Promise<{ description: string; label: string; scope: string; }[]>

Operation Id#

listApiKeyScopes

revoke()#

revoke: (id: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  createdAt: string;
  createdBy: string | null;
  expiresAt: string | null;
  id: string;
  keyPrefix: string;
  lastUsedAt: string | null;
  name: string;
  organisationId: string;
  previousKeyExpiresAt: string | null;
  revokedAt: string | null;
  rolledAt: string | null;
  scopes: string[];
}>;

Revoke an organisation API key Revokes the key immediately; embed sessions it already minted run to their expiry. Users only, holding apikeys.revoke across the whole organisation.

Parameters#

Parameter	Type
`id`	`string`
`requestOptions?`	`RequestOptions`

Returns#

Operation Id#

revokeApiKey

roll()#

roll: (id: string, request: {
  graceSeconds?: number;
}, requestOptions?: RequestOptions) => Promise<{
  apiKey: {
     accountId: string | null;
     createdAt: string;
     createdBy: string | null;
     expiresAt: string | null;
     id: string;
     keyPrefix: string;
     lastUsedAt: string | null;
     name: string;
     organisationId: string;
     previousKeyExpiresAt: string | null;
     revokedAt: string | null;
     rolledAt: string | null;
     scopes: string[];
  };
  key: string;
}>;

Roll an organisation API key Gives the key a new secret, returned in this response once, keeping its id, name, scopes, account pin and expiry. The previous secret stops working at once, or after graceSeconds (at most seven days) so the new one can be deployed first; presented after that it is refused with 401 API_KEY_ROLLED. Only one previous secret is kept, so rolling again ends the earlier one at once. A revoked or expired key cannot be rolled (409 API_KEY_NOT_ACTIVE). Users only, holding apikeys.roll across the whole organisation.

Parameters#

Parameter	Type
`id`	`string`
`request`	{ `graceSeconds?`: `number`; }
`request.graceSeconds?`	`number`
`requestOptions?`	`RequestOptions`

Returns#

Operation Id#

rollApiKey

update()#

update: (id: string, request: {
  expiresAt?: any;
  name?: string;
  scopes?: string[];
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string | null;
  createdAt: string;
  createdBy: string | null;
  expiresAt: string | null;
  id: string;
  keyPrefix: string;
  lastUsedAt: string | null;
  name: string;
  organisationId: string;
  previousKeyExpiresAt: string | null;
  revokedAt: string | null;
  rolledAt: string | null;
  scopes: string[];
}>;

Change an organisation API key Renames a key, replaces its scopes or changes its expiry (null removes it; a later one revives an expired key). New scopes apply from the key's next request; embed sessions it already minted keep theirs until they expire. Adding ledger.read is refused while the organisation does not allow API keys to read its finance data (403 API_KEY_LEDGER_READ_NOT_ALLOWED), as at creation. The key material and the account pin never change here: a new secret is a roll. A revoked key cannot be changed (409 API_KEY_NOT_ACTIVE). Users only, holding apikeys.update across the whole organisation.

Parameters#

Parameter	Type
`id`	`string`
`request`	{ `expiresAt?`: `any`; `name?`: `string`; `scopes?`: `string`[]; }
`request.expiresAt?`	`any`
`request.name?`	`string`
`request.scopes?`	`string`[]
`requestOptions?`	`RequestOptions`

Returns#

Operation Id#

updateApiKey