Memco

Class UserOperations

External users and their API keys, reached as client.users.

Every method names a user by your own id for them, the externalId they were created with.

await using client = await new Memco({ clientId, clientSecret }).connect()
const user = await client.users.create('customer-42', {
  roles: ['creator'],
  name: 'Ada'
})
Index
list get create createOrGet update delete listKeys createKey deleteKey

  • List one page of your organization's external users.

    Parameters

    Returns Promise<ExternalUserList>

    The page of users, and how many match in all.

    const page = await client.users.list({ search: 'acme' })
    console.log(page.externalUsers.map(user => user.externalId))

  • Fetch one external user, by your own id for them.

    Parameters

    • externalId: string

      Your id for the user.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<ExternalUser>

    The user.

    MemcoInvalidRequestError If externalId is blank.

    MemcoNotFoundError If you have no user with that id.

    const user = await client.users.get('customer-42')

  • Create an external user: one of your own users, known to Memco by your id for them.

    The user has no sign-in of its own, and never holds admin. It starts in no network: place it in a customer network with NetworkOperations.addMember, passing the created user's ExternalUser.id.

    Parameters

    • externalId: string

      Your id for the user, unique within your organization. It cannot be changed later.

    • options: CreateUserOptions

      The user's roles, name and email, and a deadline.

    Returns Promise<ExternalUser>

    The user as created.

    MemcoInvalidRequestError If externalId is blank, or roles is a single string or names no role.

    MemcoAlreadyExistsError If you already have a user with that id.

    const user = await client.users.create('customer-42', {
      roles: ['reader', 'creator'],
      name: 'Ada'
    })

  • Create an external user, or return the one already holding its id.

    Safe when two callers race to create one user: the loser is handed the winner's. The existing user is returned as it is; its roles, name and email are not compared with options or changed.

    Parameters

    • externalId: string

      Your id for the user, unique within your organization.

    • options: CreateUserOptions

      The user's roles, name and email, and a deadline for each call made.

    Returns Promise<ExternalUser>

    The user as created, or as it already was.

    MemcoInvalidRequestError If externalId is blank, or roles is a single string or names no role.

    MemcoNotFoundError If the user that held the id was deleted before it could be fetched.

    const user = await client.users.createOrGet('customer-42', {
      roles: ['reader', 'creator']
    })

  • Change an external user's name, email or roles.

    Parameters

    • externalId: string

      Your id for the user to change.

    • options: UpdateUserOptions = {}

      What to change, and a deadline. A field left out stays as it is; an empty name or email clears it.

    Returns Promise<ExternalUser>

    The user as it now is.

    MemcoInvalidRequestError If externalId is blank, or roles is given as a single string or naming no role.

    await client.users.update('customer-42', { roles: ['reader'] })

  • Delete an external user, and every API key it holds.

    Parameters

    • externalId: string

      Your id for the user to delete.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<void>

    MemcoInvalidRequestError If externalId is blank.

    await client.users.delete('customer-42')

  • List an external user's API keys, without their values.

    Parameters

    • externalId: string

      Your id for the user whose keys to list.

    • options: TimeoutOptions = {}

      Per-call deadline.

    Returns Promise<readonly ExternalUserKey[]>

    The user's keys. A value is shown only once, when its key is created, so none is here.

    MemcoInvalidRequestError If externalId is blank.

    const keys = await client.users.listKeys('customer-42')
    console.log(keys.map(key => [key.name, key.validUntil]))

  • Create an API key acting as an external user.

    The key's value is returned here and never again, so store it now.

    Parameters

    • externalId: string

      Your id for the user the key acts as.

    • options: CreateKeyOptions

      The kind of key, its name and expiry, and a deadline.

    Returns Promise<CreatedKey>

    The key's description, and its value.

    MemcoInvalidRequestError If externalId is blank, or validUntil is not a valid Date.

    MemcoInternalError If the service returns a value without the key it belongs to.

    const created = await client.users.createKey('customer-42', {
      preset: 'mcp_ro',
      name: 'ci'
    })
    storeSecret(created.value) // shown only this once

  • Revoke one of an external user's API keys.

    Parameters

    • externalId: string

      Your id for the user the key belongs to.

    • options: DeleteKeyOptions

      The key, and a deadline.

    Returns Promise<void>

    MemcoInvalidRequestError If externalId or keyId is blank.

    MemcoNotFoundError If the user holds no such key.

    await client.users.deleteKey('customer-42', { keyId: created.key.id })

On this page

ExampleMethodsMethodslistExamplegetThrowsThrowsExamplecreateThrowsThrowsExamplecreateOrGetThrowsThrowsExampleupdateThrowsExampledeleteThrowsExamplelistKeysThrowsExamplecreateKeyThrowsThrowsExampledeleteKeyThrowsThrowsExample