Warrant Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating Warrant involves a sequence of steps to configure the service for managing authorization within an application. This guide focuses on the initial setup, from account creation to executing a basic API call. Warrant provides a service for embedding authorization policies, supporting models like Role-Based Access Control (RBAC) and Attribute-Based Access Control (ABAC) in multi-tenant applications Warrant's core features.

The process typically includes:

1. Creating a Warrant account.
2. Generating and securing API keys.
3. Installing a Warrant SDK or preparing for direct API calls.
4. Making a first authorization request to confirm connectivity.

Quick reference table

Create an account and get keys

To begin using Warrant, developers must first create an account. Warrant offers a Developer Plan that allows up to 10,000 requests per month at no cost, which is suitable for initial testing and development.

1. Sign up: Navigate to the Warrant website and complete the registration process. This typically involves providing an email address and creating a password.
2. Access Dashboard: After signing up, you will be directed to your Warrant dashboard. This is the central location for managing your authorization policies, tenants, and API keys.
3. Generate API Keys: Within the dashboard, locate the section for API Keys. Warrant typically provides two types of keys:
• API Key: Used for server-side operations, such as creating and managing objects, users, and roles. This key should be kept secure and never exposed in client-side code.
• Client Key: Used for client-side authorization checks, often within web or mobile applications. This key is designed for public exposure but has limited permissions, usually restricted to checking existing authorization rules.
4. Secure Your Keys: It is critical to treat your API Key as sensitive information. Best practices for API key management include storing them as environment variables, using a secrets management service, or integrating with a cloud provider's secret store Google Cloud security best practices. The Client Key, while less sensitive due to its limited scope, should still be managed carefully.

Your first request

After obtaining your API keys, the next step is to make a test request to verify the integration. This involves installing a Warrant SDK or making a direct HTTPS call to the API endpoint.

Using an SDK (example: Node.js)

Warrant provides SDKs for several languages, including Node.js, Python, and Go Warrant SDKs. This example uses the Node.js SDK.

1. Install the SDK: Open your project's terminal and install the Node.js SDK:
   

   npm install @warrantdev/warrant-node

2. Initialize the SDK: In your application code, initialize the SDK with your API Key:
   

   const WarrantClient = require('@warrantdev/warrant-node');
   
   const warrant = new WarrantClient({
     apiKey: process.env.WARRANT_API_KEY,
   });

3. Define an object and subject: Before performing an authorization check, you need to define the object being accessed and the subject (user) attempting to access it. For this first request, we'll create a simple 'document' object and a 'user' subject.
   

   // Create a user
   const user = await warrant.User.create({
     userId: 'user-123',
     email: '[email protected]'
   });
   
   // Create a document
   const document = await warrant.Object.create({
     objectType: 'document',
     objectId: 'doc-abc'
   });

4. Create a Warrant: A Warrant defines an authorization relationship. For example, 'user-123' has the 'viewer' role on 'doc-abc'.
   

   // Grant user-123 the 'viewer' role on doc-abc
   await warrant.Warrant.create({
     objectType: 'document',
     objectId: 'doc-abc',
     relation: 'viewer',
     subject: {
       objectType: 'user',
       objectId: 'user-123'
     }
   });

5. Perform an authorization check: Now, check if 'user-123' can 'view' 'doc-abc'.
   

   const checkResult = await warrant.Warrant.check({
     objectType: 'document',
     objectId: 'doc-abc',
     relation: 'viewer',
     subject: {
       objectType: 'user',
       objectId: 'user-123'
     }
   });
   
   if (checkResult.result === 'Allowed') {
     console.log('User 123 is allowed to view document ABC.');
   } else {
     console.log('User 123 is NOT allowed to view document ABC.');
   }

Direct API call (example: cURL)

If you prefer to interact directly with the API, you can use tools like cURL. This example performs the same authorization check as above.

1. Define objects and subject: These would typically be created via the API first, similar to the SDK example. For this check, we assume they exist.
2. Perform authorization check: Use your API Key in the Authorization header.
   

   curl -X POST https://api.warrant.dev/v2/check
     -H 'Authorization: Api-Key YOUR_API_KEY'
     -H 'Content-Type: application/json'
     -d '{
       "object": {
         "objectType": "document",
         "objectId": "doc-abc"
       },
       "relation": "viewer",
       "subject": {
         "objectType": "user",
         "objectId": "user-123"
       }
     }'

   A successful response will indicate "result": "Allowed" or "result": "Denied".

Common next steps

After successfully making your first authorization request, consider these common next steps to further integrate Warrant into your application:

• Define Your Authorization Model: Plan out your application's authorization requirements. This might involve defining roles, permissions, and relationships between different object types Warrant authorization model concepts. Warrant supports various models, including RBAC and ABAC.
• Integrate with Your User Management System: Connect Warrant to your existing user database or identity provider (e.g., Auth0, Firebase, or a custom system) to synchronize user and tenant information Firebase Authentication documentation.
• Implement Authorization Checks Throughout Your Application: Identify critical points in your application where authorization decisions need to be made. This includes API endpoints, UI components, and data access layers.
• Explore Advanced Features: Warrant offers features like pricing tiers, multi-tenancy, and attribute-based access control. Review the Warrant multi-tenancy guide to see how these can be applied to your specific use case.
• Set Up Webhooks: Configure webhooks to receive notifications about changes in your authorization data or policy evaluations, enabling real-time reactions in your application Warrant webhooks documentation.
• Monitor and Audit: Establish monitoring for authorization requests and review audit logs to ensure policies are functioning as expected and to identify any potential security issues.

Troubleshooting the first call

Encountering issues during the initial setup is common. Here are some troubleshooting tips for your first Warrant API call:

• Incorrect API Key: Double-check that you are using the correct API Key (for server-side operations) or Client Key (for client-side checks). Ensure there are no leading or trailing spaces. Verify that the key is active in your Warrant dashboard.
• Missing or Invalid Headers: For direct API calls, ensure that the Authorization header is correctly formatted (e.g., Authorization: Api-Key YOUR_API_KEY) and that the Content-Type header is set to application/json for requests with a body.
• Network Connectivity Issues: Confirm that your server or development environment has outbound access to https://api.warrant.dev. Firewall rules or proxy settings can sometimes block these connections.
• Malformed Request Body: When making direct API calls, ensure your JSON request body is valid and adheres to the Warrant API reference specification. Even minor syntax errors can lead to rejection.
• Object/Subject Not Found: If you are checking an authorization relationship for an object or subject that hasn't been created in Warrant, the check will fail. Ensure you've created all necessary objects and subjects before performing the check.
• Rate Limiting: While less common for a first call, be aware of rate limits. If you're rapidly making multiple test calls, you might temporarily hit a limit, especially on free tiers. The Warrant pricing page details request limits.
• SDK Specific Errors: If using an SDK, consult the specific SDK's documentation for common errors and their resolutions. Ensure the SDK is initialized correctly with your API key.
• Check Warrant Dashboard Logs: The Warrant dashboard often provides detailed logs of API requests, including errors. Reviewing these logs can offer specific insights into why a request failed.