Authorize

Authorize before securely making API requests

---

After creating your access credentials, you are ready to make API calls. Most of our API clients require setting up authentication during initialization; though, it can be changed for particular requests, if needed.

If you are using a REST API, you will need to add the Authorization header as illustrated in the cURL example below.

Authorization Keys

The key used for authorization can either be:

• A Personal Access Token (PAT), which is tied to a user; or,
• An API Key, which is tied to a specific application.

IMPORTANT NOTE

• PAT is the primary authentication mechanism we use.

Using a PAT is more powerful than an API Key. A PAT represents you when accessing the Clarifai API. It allows you to access multiple applications with a single key.

With a PAT, you can access your own apps as well as any other apps you have permissions to use, such as public apps, apps you're added as a collaborator, or apps belonging to your organization's team. Also, certain endpoints support only PATs, such as creating a new application or a new API Key.

When using a PAT to call the API, you need to specify your user ID alongside the application ID to which the request should be applied.

On the other hand, an API Key restricts your access only to a single app. So, it could be suitable for accessing resources that are specifically locked down to a single app.

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

tip

Clarifai provides various clients you can use to access the API in your favorite programming language. Learn how to install your preferred client here.

Authorization Examples

Python

###############################################################################################
# Initialize the gRPC-based client to communicate with the Clarifai platform.
###############################################################################################

# Import the Clarifai gRPC-based objects needed
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_pb2, status_code_pb2

# Construct the communications channel 
channel = ClarifaiChannel.get_grpc_channel()
# Construct the V2Stub object for accessing all the Clarifai API functionality
stub = service_pb2_grpc.V2Stub(channel)

##############################################################################################
# This is where you set up the metadata object that's used to authenticate. 
# This authorization will be used by every Clarifai API call.
# Change the following authorization key to your own credentials
# Example: metadata = (('authorization', 'Key ' + 'a123457612345678'),)
##############################################################################################
 
metadata = (('authorization', 'Key ' + 'YOUR_CLARIFAI_PAT_HERE'),)
# Or, if you were to use an API Key:
# metadata = (('authorization', 'Key ' + 'YOUR_CLARIFAI_API_KEY_HERE'),)
# Yes, the word 'Key' appears in addition to the alphanumeric PAT or API Key

##############################################################################################
# A UserAppIDSet object is needed when using a PAT. It contains two pieces of information: 
# user_id (your user id) and app_id (app id that contains the model of interest). 
# Both of them are specified as string values.
##############################################################################################

userDataObject = resources_pb2.UserAppIDSet(user_id='YOUR_USER_ID_HERE', app_id='YOUR_APPLICATION_ID_HERE')

NodeJS

/////////////////////////////////////////////////////////////////////////////////////////////
// Initialize the gRPC-based client to communicate with the Clarifai platform.
////////////////////////////////////////////////////////////////////////////////////////////

// Import the Clarifai gRPC-based client
const {ClarifaiStub, grpc} = require("clarifai-nodejs-grpc");

// Construct the stub object for accessing all the Clarifai API functionality
const stub = ClarifaiStub.grpc();

////////////////////////////////////////////////////////////////////////////////////////////
// This is where you set up the Metadata object that's used to authenticate. 
// This authorization will be used by every Clarifai API call.
// Change the following authorization key to your own credentials
// Example: metadata.set("authorization", "Key " + "a123457612345678");
////////////////////////////////////////////////////////////////////////////////////////////

const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + "YOUR_CLARIFAI_PAT_HERE");
// Or, if you were to use an API Key:
// metadata.set("authorization", "Key " + "YOUR_CLARIFAI_API_KEY_HERE");
// Yes, the word 'Key' appears in addition to the alphanumeric PAT or API Key

/////////////////////////////////////////////////////////////////////////////////////////////
// A UserAppIDSet object is needed when using a PAT. It contains two pieces of information: 
// user_id (your user id) and app_id (app id that contains the model of interest). 
// Both of them are specified as string values.
/////////////////////////////////////////////////////////////////////////////////////////////

user_app_id: {
    "user_id": "YOUR_USER_ID_HERE",
    "app_id": "YOUR_APPLICATION_ID_HERE"
}

Java

/////////////////////////////////////////////////////////////////////////////////////////////
// Initialize the gRPC-based client to communicate with the Clarifai platform.
////////////////////////////////////////////////////////////////////////////////////////////

// Import the Clarifai gRPC-based objects needed
import com.clarifai.grpc.api.*;
import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;

/////////////////////////////////////////////////////////////////////////////////////////////
// Construct the communications channel.
// Construct the stub object for accessing all the Clarifai API functionality.
// Set up the authorization that will be used by every Clarifai API call.
/////////////////////////////////////////////////////////////////////////////////////////////

Channel channel = ClarifaiChannel.INSTANCE.getGrpcChannel();

V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(channel)
.withCallCredentials(new ClarifaiCallCredentials("YOUR_CLARIFAI_PAT_HERE"));

// Or, if you were to use an API Key:
//.withCallCredentials(new ClarifaiCallCredentials("YOUR_CLARIFAI_API_KEY_HERE"));

/////////////////////////////////////////////////////////////////////////////////////////////
// A UserAppIDSet object is needed when using a PAT. It contains two pieces of information: 
// user_id (your user id) and app_id (app id that contains the model of interest). 
// Both of them are specified as string values.
/////////////////////////////////////////////////////////////////////////////////////////////

.setUserAppId(UserAppIDSet.newBuilder().setUserId("YOUR_USER_ID_HERE").setAppId("YOUR_APPLICATION_ID_HERE"))

PHP

/////////////////////////////////////////////////////////////////////////////////////////////
// Initialize the gRPC-based client to communicate with the Clarifai platform.
////////////////////////////////////////////////////////////////////////////////////////////

// Enable use of the ClarifaiClient object from the Clarifai namespace
use Clarifai\ClarifaiClient;

// Construct the initialization object for accessing all the Clarifai API functionality
$client = ClarifaiClient::grpc();

////////////////////////////////////////////////////////////////////////////////////////////
// This is where you set up the Metadata object that's used to authenticate. 
// This authorization will be used by every Clarifai API call.
// Change the following authorization key to your own credentials
// Example: $metadata = ['Authorization' => ['Key a123457612345678']];
////////////////////////////////////////////////////////////////////////////////////////////

$metadata = ['Authorization' => ['Key YOUR_CLARIFAI_PAT_HERE']];

// Or, if you were to use an API Key:
// $metadata = ['Authorization' => ['Key YOUR_CLARIFAI_API_KEY_HERE']];
// Yes, the word 'Key' appears in addition to the alphanumeric PAT or API Key

/////////////////////////////////////////////////////////////////////////////////////////////
// A UserAppIDSet object is needed when using a PAT. It contains two pieces of information: 
// user_id (your user id) and app_id (app id that contains the model of interest). 
// Both of them are specified as string values.
/////////////////////////////////////////////////////////////////////////////////////////////

use Clarifai\Api\UserAppIDSet;

$userDataObject = new UserAppIDSet([
    'user_id' => 'YOUR_USER_ID_HERE', 
    'app_id' => 'YOUR_APPLICATION_ID_HERE' 
]);

cURL

curl -X POST \
  -H "Authorization: Key YOUR_CLARIFAI_PAT_HERE" \
  -H "Content-Type: application/json" \  

C#

using System.Threading.Tasks;
using Clarifai.API;
namespace YourNamespace
{
    public class YourClassName
    {
        public static async Task Main()
        {
            var client = new ClarifaiClient("YOUR_API_KEY");
        }
    }
}

Objective-C

ClarifaiApp *app = [[ClarifaiApp alloc] initWithApiKey:@"YOUR_API_KEY"];

caution

• If your PAT or API Key does not have the required scope(s) to execute a given request, you will get an error message reporting the missing scopes and/or endpoints that are needed to execute the request.
• An invalid PAT or API Key may be reported as 'API key not found'.
• Failure to include the required PAT or API Key may result in 'Invalid request'.

CORS Policy

Our APIs adhere to industry standards for Cross-Origin Resource Sharing (CORS) to ensure security and proper access control. The Access-Control-Allow-Origin header is limited to a predefined list of allowed origins.

This means that only requests originating from allowed origins will receive a successful CORS response. If your Javascript application(s) encounter a CORS error while calling our APIs, it is likely that the origin is not on the allowed list.

To avoid such issues, we recommend following established patterns such as using a backend server to proxy API requests or ensuring your application is hosted on an approved origin.

For more information about CORS and best practices, you can refer to this resource.

If you need additional support or would like to request for your custom domain, please reach out to support@clarifai.com for assistance.