Add a name to the API Keys

[bidoubiwa]

Problem

For the moment the API keys (defaults and generated) only have descriptions. Thus, there is no way to quickly find the key and its specifications unless you have the key.

For example, if we want to restrict the access of this specific key:

      {
          description: 'This is a key that I created',
          key: 'sw3qLtL1e2ee6b9297b2f7e849e01ea05ae56812ab8bad4d2d07fbf6184801037315843d',
          actions: [ '*' ],
          indexes: [ 'movies' ],
          expiresAt: null,
          createdAt: '2021-12-13T11:58:55.077949400Z',
          updatedAt: '2021-12-13T11:58:55.077949918Z'
        }

The user need either to know the key, or to make some sort of finding function.

Example:

If I try to get the default admin key automatically:

const keys = await client.getKeys()
const privateKey = keys.find((key) =>key.description.startsWith('Default Admin API'))

If I try to change the permission of a generatedkey of which I do not know the value anymore:

{
    "description": "Indexing Products API key",
    "actions": [
        "documents.add"
    ],
    "indexes": ["products"],
    "expiresAt": "2021-11-13T00:00:00Z"
}

const apiKey = (await client.getKeys()).find(
      (key) =>
        key.indexes.contains('products') && key.actions.contains('document.add')
    )
apiKey.actions.push('search')

The best option for the user would be to make the description field act as a name field:

{
    "description": "product_admin", // for example
    "actions": [
        "documents.add"
    ],
    "indexes": ["products"],
    "expiresAt": "2021-11-13T00:00:00Z"
}

Suggestion

I would like to have a name field or a role field to be able to filter on them easily. As a bonus it also brings a lot of clarity in which key you need to spread amongst which population.

If you have in your app moderators and admins you can quickly automate their access to these keys.

[gmourier]

Hi @bidoubiwa! 👋 Thanks for the feedback!

It is indeed a good future possibility. If I summarize it, the need is to be able to filter a list of API Keys to reduce it to some specific ones?

I don't really see the direct point of adding another field for that while description could be useful but I may be wrong 😇

If the main need is to retrieve a reduced amount of API Keys matching some criteria we could also add more filters on indexes / actions / expiresAt in addition to description.

What do you think?

[bidoubiwa]

Hey @gmourier thanks for you response :) The idea is not to reduce the list, while that could be very nice as well now that you mention it. It is more about accessing the key in an other environment than the one the key has been created.

For example, if I create a key in one place and want to fetch it in another I do not have the API key in the second place.
To retrieve the key in this place I will need to find the key by making a request on /keys route.
After which, for me to find that specific key, I would need to find the key based on some criteria. In my case for the moment it is by comparing the content of description.
I find that description is not meant to be the field that represents the key.

Imagine, a more suited attribute name could be roleName or role, that could have moviesAdmin as value, in case I want to create a key that has only access to movies index.
In the second part of my code base, to retrieve the key this would be my code:

const key = keys.find(key => key.roleName === "moviesAdmin")

Thanks to this, in the place where I created the key, I can update it or even re-created the key with the same roleName, and it will not impact the place where the token is retrieved as the code above does not need to be changed.

Whereas description is more meant to be an explanation like this key gives create/update/delete access on the documents contained in the movies index.

I imagine that in the future if we do add a field like that, it could be in the search parameters when using GET /keys?roleName=moviesAdmin or other parameters. In both cases I think having that field is great and maybe expected. It could also serve as a human-readable unique identifier.

If I look at what other engines do:

• elasticSearch requests a name field.
• mongoDb requests an apiKeyName

const key = await user.apiKeys.create("apiKeyName");

• Algolia does not it appears
• typesense does not
• couchbase uses api key name
• ravenDb also have names for their apikey
• redis uses api key name
• neo4j uses a role system
• amazon dynamoDb uses a role system

(I have a hard time finding the API route for couchbase and ravenDB, I only have the doc for their saas)

Conclusion

I think a field called name or role may be expected (per example above) and is also very useful in a lot of use cases. In a later itteration being able to search on a role as a query parameter of the GET /keys route would be great but meanwhile having only name is already a good alternative.

[irevoire]

Same, as a user when I get an array of keys and I want to extract my private or search key it feels really bad to parse the description field... I’m not supposed to be scrapping my own API to use it 😂

To me the description should be left for the humans to read it.
And a name or role field should be made for automation and scripting as @bidoubiwa said 👍

[brunoocasali]

In addition to what @irevoire and @bidoubiwa said. Suppose our developer created a page for their admins to create and edit keys in an admin page. And the developer needs to use a particular key to some internal reference.

The developer internally can't rely on the descriptions, because they're editable.
Isn't a programmatic field you could use internally.

I'm not sure about the naming of the role is a good name or could be misunderstood with indexes and actions purpose, for me, the role is more related to a group of indexes and actions that key could access. For example: admins-only, anonymous-users, read-only.

What about a (unique-and-create-field-only) field that is created in the POST /keys and can't be updated?