Skip to main content

App-Specific API Keys

Authenticate access to resources within the scope defined by the key

App-specific API Keys are used to authorize access to your Clarifai applications. You can use an API Key to access the resources within the scope of the app defined by that key.

A key is automatically generated when you create a new application. You can also go to the Application's List on the Portal, select an app of your choice, and create a new key on the app details page.

info

Each API Key is associated with a specific user and a specific app. It ties in user_id and app_id, causing only resources in that app to be usable.

When using an app-specific API Key to make a request, you do not need to specify either the user ID or the application ID, as they are already part of the API Key.

An API Key allows you to have fine-grained control over the data exposed through your app. You can control the scope of your API Key through a simple checkbox interface displayed when you create a new key or edit a key.

tip

You cannot use an API key to access models, model versions, workflows, and other resources that are not part of the app that the API key is associated with. You need a PAT to do so. For example, to access any of Clarifai's resources, you need to use a PAT while specifying Clarifai's user_id and the app_id to which the resource belongs.

How to Create API Keys on the Portal​

Navigate to your application's individual page and select the Settings option on the collapsible left sidebar.

You'll be redirected to the App Settings page.

Within the API Keys section, click the Create API Key button.

App settings create key

Then, use the form that pops up to generate a new API key for your application—provide a short description, select the scopes, and click the Confirm button.

App key create form

The new key will be listed in the API Keys section, where you can copy it to the clipboard, edit it, or delete it.

copy, edit, delete api key

How to Create API Keys Programmatically​

For enterprise users, it is also possible to generate keys programmatically.

If you are managing the work of multiple users, who's data, models, and concepts that need to be segregated, we recommend you create keys this way. This ensures that each individual user only has access to their own private resources.

tip

You need to use a Personal Access Token (PAT) to create an API Key. 

curl --location --request POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/keys" \
--header "Content-Type: application/json" \
--header "Authorization: Key YOUR_PAT_HERE" \
--data-raw '{
    "keys": [
        {
            "description": "All permissions",
            "scopes": [
                "All"
            ],
            "apps": [
                {
                    "id": "YOUR_APP_ID_HERE",
                    "user_id": "YOUR_USER_ID_HERE"
                }
            ]
        }
    ]
}'
caution

  • API Keys do not expire. In case your API Key gets compromised, you should delete that key, and create a new one with the same scopes.

  • We recommend that you do not share your API Key with other users.

How to Use an API Key Example​

Here is an example of how to use an API Key to make a prediction request from your own model. Note that your user_id and app_id are already tied to the key, so no need to specify them.

###################################################################################
# In this section, we set the user authentication, model details, and the URL
# of the image we want as an input. Change these strings to run your own example.
###################################################################################

# Your API Key can be found in the portal under your App's settings
KEY = 'YOUR_APP_KEY_HERE'
MODEL_ID = 'YOUR_MODEL_ID_HERE'
# This is optional. You can specify a model version or the empty string for the default
MODEL_VERSION_ID = ''
IMAGE_URL = 'https://samples.clarifai.com/metro-north.jpg'

############################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
############################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + KEY),)

post_model_outputs_response = stub.PostModelOutputs(
    service_pb2.PostModelOutputsRequest(
        model_id=MODEL_ID,
        version_id=MODEL_VERSION_ID,  
        inputs=[
            resources_pb2.Input(
                data=resources_pb2.Data(
                    image=resources_pb2.Image(
                        url=IMAGE_URL
                    )
                )
            )
        ]
    ),
    metadata=metadata
)
if post_model_outputs_response.status.code != status_code_pb2.SUCCESS:
    print(post_model_outputs_response.status)
    raise Exception("Post model outputs failed, status: " + post_model_outputs_response.status.description)

# Since we have one input, one output will exist here
output = post_model_outputs_response.outputs[0]

print("Predicted concepts:")
for concept in output.data.concepts:
    print("%s %.2f" % (concept.name, concept.value))

# Uncomment this line to print the full Response JSON
#print(output)