Authentication

The G-Tateth API supports two authentication methods: API keys (recommended for server-to-server) and JWT tokens (for user-authenticated requests).

API Key Authentication

API keys are the recommended method for server-to-server communication. They provide secure, long-lived access to the API.

Creating an API Key

Log in to your G-Tateth account
Navigate to Settings → Developer Console
Click “Create API Key”
Choose your environment (Production or Staging)
Select permissions for the key
Copy your API key (it’s only shown once!)

Using Your API Key

Include your API key in the Authorization header:

curl -H "Authorization: Bearer sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations

Or use the X-API-Key header:

curl -H "X-API-Key: sk_live_your_api_key_here" \
  https://api.g-tateth.com/api/v1/conversations

API Key Types

Production keys (sk_live_...) - Use in production environments
Test keys (sk_test_...) - Use for development and testing

Test keys are automatically blocked in production environments for safety.

API Key Permissions

When creating an API key, select only the permissions it needs (principle of least privilege):

Permission	Grants access to
`read:conversations`	List and retrieve conversations
`write:conversations`	Create, update, and delete conversations
`read:customers`	List and retrieve customer profiles
`write:customers`	Create, update, and delete customer profiles
`webhook:manage`	Create, update, delete, test, and view logs for webhooks
`read:analytics`	Access usage statistics and performance metrics

See the API Keys reference for more details.

API reference and Swagger UI

The interactive Swagger UI (requires JWT session) is at:

https://api.g-tateth.com/api-docs/

The raw OpenAPI spec (for Postman, code generators, and contract tests):

https://api.g-tateth.com/api-docs/spec.json

JWT Authentication

JWT tokens can be used for user-authenticated requests. Obtain a JWT token through the authentication endpoints.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.g-tateth.com/api/v1/conversations

Security Best Practices

Never commit API keys to version control - Use environment variables
Rotate keys regularly - Set up automatic rotation if possible
Use test keys for development - Keep production keys secure
Limit permissions - Only grant the minimum permissions needed
Use IP whitelisting - Restrict API key access to specific IPs
Monitor usage - Regularly check API key usage logs

Error Responses

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "success": false,
  "error": "Invalid or expired API key",
  "code": "API_KEY_INVALID"
}

Common error codes:

API_KEY_INVALID - Invalid API key
API_KEY_EXPIRED - API key has expired
API_KEY_INACTIVE - API key is inactive
TENANT_SUSPENDED - Tenant account is suspended

Get Started

Guides

Integrations

SDKs

Resources

API Key Authentication

Creating an API Key

Using Your API Key

API Key Types

API Key Permissions

API reference and Swagger UI

JWT Authentication

Security Best Practices

Error Responses

​API Key Authentication

​Creating an API Key

​Using Your API Key

​API Key Types

​API Key Permissions

​API reference and Swagger UI

​JWT Authentication

​Security Best Practices

​Error Responses

API Key Authentication

Creating an API Key

Using Your API Key

API Key Types

API Key Permissions

API reference and Swagger UI

JWT Authentication

Security Best Practices

Error Responses