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 create a new one, as described below.

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 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 key through a simple checkbox interface displayed when you create a new key or edit a key.

API Key Versus PAT

You cannot use an API Key to access models, model versions, workflows, or other resources that are not part of the app that the 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 Platform​

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 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.

note

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"
                }
            ]
        }
    ]
}'
note
  • API Keys do not expire. In case your key gets compromised, you should delete it, 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.

Set API Key as an Environment Variable

It's a good practice to load your API Key from an environment variable. Keeping your key in a secrets manager, and not in the source code, improves its security and management.

##################################################################################################
# FOR SECURE AUTHENTICATION, SET API KEY AS AN ENVIRONMENT VARIABLE
#################################################################################################

# The built-in Python os library provides functions to access and manipulate environment variables
import os

# Python-dotenv reads key-value pairs from a .env file and can set them as environment variables
# Install the library by running `pip install python-dotenv`
from dotenv import load_dotenv

load_dotenv()

# Set the `CLARIFAI_API_KEY` environment variable before running the code. For example, you can set it in an .env file as `export CLARIFAI_API_KEY=YOUR_API_KEY_HERE`
# Your API Key can be found in the platform in your app's settings page

KEY = os.getenv('CLARIFAI_API_KEY')
if KEY is None:
    raise ValueError("API Key is not set. Please set the CLARIFAI_API_KEY environment variable.")

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

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)
© 2024 Clarifai, Inc. All rights reserved