Skip to main content

Authentication

This document provides detailed instructions on how to authenticate with the Tianji API, including obtaining, using, and managing API keys.

Authentication Method​

The Tianji API uses Bearer Token authentication. You need to include your API key in the HTTP header of each API request.

HTTP Header Format​

Authorization: Bearer <YOUR_API_KEY>

Obtaining API Keys​

  1. Log in to your Tianji instance
  2. Click on your avatar in the top right corner
  3. Find the API Keys section
  4. Click the + button to create a new API key
  5. Name your API key and save it

API Key Management​

View Existing Keys​

In the API Keys section, you can see:

  • API key name/description
  • Creation date
  • Last used time
  • Usage count statistics

Delete API Keys​

If you need to revoke an API key:

  1. Find the API key you want to delete
  2. Click the Delete button
  3. Confirm the deletion operation
Note

After deleting an API key, all applications using that key will no longer be able to access the API.

Using API Keys​

cURL Example​

curl -X GET "https://your-tianji-domain.com/open/global/config" \
  -H "Authorization: Bearer <your_api_key_here>" \
  -H "Content-Type: application/json"

JavaScript/Node.js Example​

const apiKey = '<your_api_key_here>';
const baseUrl = 'https://your-tianji-domain.com/open';

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

// Using fetch
const response = await fetch(`${baseUrl}/global/config`, {
  method: 'GET',
  headers: headers
});

// Using axios
const axios = require('axios');
const response = await axios.get(`${baseUrl}/global/config`, {
  headers: headers
});

Python Example​

import requests

api_key = '<your_api_key_here>'
base_url = 'https://your-tianji-domain.com/open'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

# Using requests library
response = requests.get(f'{base_url}/global/config', headers=headers)
data = response.json()

PHP Example​

<?php
$apiKey = '<your_api_key_here>';
$baseUrl = 'https://your-tianji-domain.com/open';

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl . '/global/config');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
?>

Permissions and Scope​

API Key Permissions​

API keys inherit all permissions of their creator, including:

  • Access to all data in the user's workspaces
  • Execute all operations the user has permission for
  • Manage resources created by that user

Workspace Access​

API keys can only access workspaces that the user belongs to. If you need to access multiple workspaces, ensure your user account has appropriate permissions for those workspaces.

Error Handling​

Common Authentication Errors​

401 Unauthorized​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization not provided"
  }
}

Causes:

  • No Authorization header provided
  • Incorrect API key format

403 Forbidden​

{
  "error": {
    "code": "FORBIDDEN", 
    "message": "Insufficient access"
  }
}

Causes:

  • Invalid or deleted API key
  • User doesn't have permission to access the requested resource

Debugging Authentication Issues​

  1. Check API key format: Ensure you're using the Bearer token_here format
  2. Verify key validity: Confirm the key still exists in the Tianji interface
  3. Check permissions: Ensure the user account has permission to access the target resource
  4. Test simple endpoints: Start by testing public endpoints like /global/config