Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-docs.nunu.ai/llms.txt

Use this file to discover all available pages before exploring further.

All nunu.ai API requests require authentication using an API key. This page covers how to create, manage, and use API keys.

​
Creating API Keys

1

Navigate to API Keys

Go to Project Admin → API Keys in the nunu.ai dashboard
2

Create a new key

Click Create API Key
3

Select permissions

Choose the permissions your key needs based on your use case
4

Save your key

Copy and securely store your key—it won’t be shown again
API keys are sensitive credentials. Never commit them to version control or expose them in client-side code.

​
Using API Keys

Include your API key in the X-Api-Key header with every request: 
GET /api/v1/runs HTTP/1.1
Host: nunu.ai
X-Api-Key: YOUR_API_TOKEN

curl -X GET "https://nunu.ai/api/v1/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN"

​
Permissions

API keys are scoped to specific permissions. Request only the permissions your integration needs:
PermissionDescriptionEndpoints
project:read-runsRead run data, artifacts, and bug reportsGET /runs, GET /runs/{id}, GET /runs/{id}/bugs
project:operate-runsStart and stop test runsPOST /runs, POST /runs/stop
project:manage-build-storageUpload, manage, and delete buildsAll /builds/* endpoints

​
Combining Permissions

A single API key can have multiple permissions. For example, a CI/CD integration might need both project:manage-build-storage (to upload builds) and project:operate-runs (to trigger tests).

​
Key Management Best Practices

​
Use Environment Variables

Store API keys in environment variables, not in code: 
# Set in your CI/CD environment or shell profile
export NUNU_API_TOKEN=your_token
export NUNU_PROJECT_ID=your_project_id

​
Rotate Keys Regularly

1

Create new key

Create a new API key with the same permissions
2

Update integrations

Update all integrations with the new key
3

Deactivate old key

Deactivate the old key after confirming the transition works

​
Use Separate Keys for Different Purposes

Permissions: project:manage-build-storage + project:operate-runsUse for uploading builds and triggering tests from your CI/CD pipeline.
Permissions: project:read-runs onlyUse for read-only access to view test results and run history.
Permissions: project:manage-build-storage onlyUse when you only need to upload builds without triggering tests.

​
Monitor Key Usage

Check the Last Used timestamp in Project Admin → API Keys to identify unused keys that should be removed.

​
Key Expiration

API keys can be configured with an expiration date. After expiration, requests with that key will receive a 403 Forbidden response.
To avoid disruption:
  • Set calendar reminders before key expiration
  • Create replacement keys in advance
  • Monitor for 403 errors in your integrations

​
Error Responses

​
Missing API Key (401)

{
  "error": "API key required"
}
Solution: Include the X-Api-Key header in your request.

​
Invalid API Key (401)

{
  "error": "Invalid API key"
}
Solution: Verify your API key is correct and hasn’t been deactivated.

​
Expired API Key (403)

{
  "error": "API key expired"
}
Solution: Create a new API key and update your integration.

​
Disabled API Key (403)

{
  "error": "API key is disabled"
}
Solution: Re-enable the key in Project Admin or create a new one.

​
Missing Permission (403)

{
  "error": "API key missing required permission: project:operate-runs"
}
Solution: Edit the API key to add the required permission, or create a new key with the needed permissions.

​
Security Recommendations

Server-Side Only

API keys should only be used in server-side or CI/CD environments

HTTPS Only

All API requests must use HTTPS

Least Privilege

Grant only the permissions each integration needs

Regular Audits

Review and remove unused API keys regularly
In CI/CD, use your platform’s secrets management (GitHub Secrets, GitLab CI Variables, Jenkins Credentials, etc.) to securely store API keys.