Skip to main content
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.