API Keys

Overview

API keys allow you to access the Giselle API programmatically to run your apps from external applications, scripts, or services. API keys are scoped to your team, meaning all team members share access to the same set of API keys.

Creating an API Key

API Key Format

API keys follow the format:

gsk_<id>.<secret>

For example: gsk_abc123xyz.secret_value_here

When viewing your API keys in the settings, you'll see a redacted version showing only the first few and last few characters (e.g., gsk_abc...xyz).

Managing API Keys

Viewing API Keys

The API Keys page displays all keys for your team with the following information:

• Label: The descriptive name you assigned
• Redacted Value: A shortened version of the key for identification
• Created At: When the key was created
• Last Used At: When the key was last used for an API request

Revoking API Keys

To revoke an API key:

1. Navigate to Settings > Team > API Keys
2. Find the key you want to revoke
3. Click the Revoke button
4. Confirm the revocation

Using API Keys

When making requests to the Giselle API, include your API key in the Authorization header:

curl -X POST https://studio.giselles.ai/api/apps/{appId}/run \
  -H "Authorization: Bearer gsk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your input text"}'

For a better developer experience, consider using the Giselle SDK which handles authentication automatically.

Security Best Practices

Rate Limits

API requests are rate-limited based on your team's plan:

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Rate limit information is included in response headers:

• RateLimit-Limit: Maximum requests allowed per minute
• RateLimit-Remaining: Remaining requests in the current window
• RateLimit-Reset: Unix timestamp when the rate limit resets
• Retry-After: Seconds to wait before retrying (when rate limited)

Troubleshooting

Unauthorized (401) Error

If you receive a 401 error, check that:

• Your API key is correct and complete
• The key hasn't been revoked
• The Authorization header is formatted correctly: Bearer <your_api_key>

Rate Limited (429) Error

If you're being rate limited:

• Check the Retry-After header for when you can retry
• Consider upgrading your plan for higher limits
• Implement exponential backoff in your application

Next Steps

• Learn how to use the Giselle SDK for easier API integration
• Explore the Playground to test your apps before integrating via API