All About API Keys!

Ahh...authentication. One of the more unglamorous parts of an API, but yet, one of the most important! Let's chat a bit about how to do it with our platform.

With API Keys you can:

• Apply scopes (described more below). Old access tokens applied to every single part of the API, but Keys can be applied towards only certain operations like Predicting, if desired. This is good for large teams that want to delegate certain permissions to certain people
• Share your code with more ease. For example, an API Key could be used to make client-side calls to the Clarifai API from a website or embedded into a mobile app; this key could only contain Predict permissions, hence preventing users from making changes to the model/app that you have created.
• Delete and temporarily remove them, unlike our deprecated access tokens, which had to live for 48 hours

Scopes

So what exactly are these scope things that we're talking about? By default you will see this on the API Keys page in your application (link above):

These six options are fairly easy to understand, but if we click on "Advanced" in the top right corner then we are given much more granularity! 

Let's take a deeper look at all the different items that you can select here. An asterisk (*) means that an item has pre-requisites in order to be used:

All

Pretty self-explanatory, this scope will give access to everything that our API offers, which is essentially what our Access Tokens do. Good for admins to have, but not so great for everyone, so use with caution.

Predict

This scope will either let a user makes calls to public/custom models or provide feedback on the results, depending on which checkboxes you select for it (you can select one or both). The first of these consumes Operations, so make sure you assign this to the right people! Providing feedback is totally free.

Search

Similar to the Predict scope, this will allow users to perform any searches on inputs in your application (which also incur an Operation). There is only one checkbox here, so this applies to all searches.

Inputs

Now it starts to get a little tricky, because the Inputs scope has four different options that you can choose from instead of just one or two. Let's go through all of them:

• Add: Allows a user to add new inputs to an application via the API. Adds incur an operation.
• Get: Allows a user to look up the currently existing inputs of an application, but there is a catch! If you don't also have the "Get" permission from Concepts (below), they will not be able to see the input's concepts, just its other info (like URL or metadata)
• Patch*: Allows a user to edit or tweak an existing input's data (e.g. adding a concept to it), and the "Get" permission needs to be activated as a pre-req. Thus, Patch and Get will always be active together, and never Patch by itself. Patches also incur an Operation.
• Delete*: Allows a user to be able to delete an input from an application. Like Patch, it is also required that Get is selected.

Concepts

Custom Training concepts (or tags, if you prefer to call them that) have their own permissions as well:

• Add: Allows a user to add new concepts to a model or application. This incurs an Operation.
• Get: Allows a user to read concepts from Inputs. This will need to be set in order for [Inputs: Get] to work
• Patch*: Allows a user to rename a concept in a model or application, which incurs an Operation. The "Get" permission needs to be set in order for this to be activated.

Models

And finally - there are different permission levels for our nifty Custom Models! This one has the most individual items of any category:

• Add: Allows a user to create a new custom model, which would be in a particular application
• Get: Allows a user to retrieve all of the models that are within a particular application
• Patch*: Allows a user to edit a model, which includes deleting concepts, renaming the model, changing the mutually_exclusive or closed_environment properties and adding concepts. This requires both the "Get" and "Train" permissions because of all of the stuff that it allows!
• Delete*: Allows a user to delete a model entirely. Requires the "Get" permission.
• Train*: Allows a user to train a particular model, and requires the "Get" permission. A Train incurs an Operation.

So what happens if I call something out of scope?

If the API Key does not have the required scope(s), you will receive one of the following responses:

1. Rejected Request: if a large portion of the response requires a scope that is missing, you will not receive any information back (other than an error)
2. Redacted Response: if majority of the response has the required scope(s), a small portion of the response will be redacted to not reveal unwarranted information

Error Codes

If you get an error related to your key it will fall under one of the following categories: