Skip to main content
The One Codex API supports two methods of authentication. Only secure connections (HTTPS) are allowed.

​
HTTP Basic Auth

Use your API key as the username and an empty password:

​
API Key Header

Alternatively, you can pass your API key in the X-API-Key header:
Both methods are equivalent. The API key header approach is what the API playground examples on this site use. As our API supports access to public samples, projects, and analyses, unauthenticated access is permitted and may return empty result sets rather than a 401. If you see empty result sets, check that you’re properly authenticated by accessing a protected resource, e.g., a private Sample owner by your account or the Account info resource (https://app.onecodex.com/api/v1/account). Unauthenticated requests against protected routes will return a 401 Unauthorized. Unauthorized requests will return a 403 Forbidden. Unauthenticated or unauthorized requests for a protected resource (i.e., a private sample) may return a 404 Not Found in order to not expose the existence of private records.
Your API key is effectively a plain text password for accessing your uploads and analyses. Please keep it secure! If you lose your key, accidentally publish it to GitHub or another public place, or otherwise believe it could have been compromised, simply generate a new API key in the Settings pane of the One Codex web application. This will automatically revoke your old key.Our API servers also support JWT-based authentication, which offer different security and usability tradeoffs. We plan to make JWT token generation available via the Settings page in the near future.

​
Locating your API key

You can find your API key under the Settings menu in the top-right corner of the One Codex web application: Within the Settings menu, you should see a panel called Account Info & Security. Click the button under “Your API Key” to reveal your key. Again, keep this key secret!

​
Generating a new API key

If you lose access to your API key, accidentally publish it in a public place, or otherwise need to replace it, you can simply regenerate a new key on the Settings page: Please note: You will need to update any code, configuration files, or environmental variables using the key.