Authentication

The One Codex API uses HTTP Basic Auth for authentication by default. Only secure connections (HTTPS) are allowed. Use your API key as the username and an empty password to authenticate:

curl https://app.onecodex.com/api/v1/schema -u $ONE_CODEX_API_KEY:

http --auth $ONE_CODEX_API_KEY: https://app.onecodex.com/api/v1/schema

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.

{
    "message": "The server could not verify that you are authorized to access the URL requested.  You either supplied the wrong credentials (e.g. a bad password), or your browser doesn't understand how to supply the credentials required.",
    "status": 401
}

🚧

Protecting Your API Keys

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.