Generating an API Key

How to Generate an API key

First, go to 'my profile' located under your initials on the top-right hand corner.

Next, click on 'API Keys.'

Enter the name of your API Key and select an expiration date. 

Finally, click 'create' and your API key will appear on the page. Remember to be as secure as possible with your API key.

Constraining your API Key

With API scoping, you have the ability to generate an API key whose permissions you can restrict as you see fit.

Creation of a scoped API key happens in your Civis User Profile on the bottom-right portion of the page.  It's here that you can set the type, constraint text, and set of allowed HTTP methods.  If you have multiple constraints on a key, they are OR'd together.  A request will be allowed if it matches any of the constraints.

For constraint types, you can choose between:

• exact - Allows requests only to the specified path.  For example, putting in "jobs" would allow the key to only access the /jobs endpoint.
• prefix - Allows requests to any path that begins with the constraint text.  For example, putting in "jobs" would allow the key to access the /jobs, /jobs/:id, and /jobs/:id/runs endpoints.
• regex - Allows requests to the paths matching the provided regex.  There are implicit \A and \z matchers wrapping the regex.
• verb - Allows requests to any path that matches one of the HTTP verbs.  Maybe you want to be sure a key can only POST or only GET.

If you plan to use a constrained API key with a Civis API client (such as our Python client), you will need to add "endpoints" as a prefix constraint.  The /endpoints endpoint is used to generate the client dynamically.

Make sure to be as conservative as possible when constraining API keys.  You don't want someone else to be able to access endpoints that are unnecessary or inappropriate.

API Key Management Best Practices

When you use the Civis API keys in your applications, take care to keep them secure.  Publicly exposing your credentials can result in your account being compromised, which could lead to unexpected changes on your account and exposure of your private data.  To keep your API keys secure, follow these best practices:

• Make API calls within Civis: API calls that are made within Civis (using civis.api.call() in a Javascript script, for example) automatically generate and clean up API keys for you, preventing API keys from ever being exposed externally.
• Do not embed API keys directly in code: API keys that are embedded in code can be accidentally exposed to the public -- for example, if you forget to remove the keys from the code that you share.  Instead of embedding your API keys in your scripts or applications, store them in environment variables.
• Do not store API keys in files inside your application's source tree: If you store API keys in files, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system.  This is particularly important if you use a public source code management system such as GitHub.
• Constrain the scope of API keys embedded in applications: It is possible to limit the scope of an API key using constraints.  If you are using an API key as part of a specific application, we recommend that you constrain the API key to the minimum set of permissions necessary to allow the application to execute successfully to minimize the risk should that API key become compromised.
• Delete unneeded API keys: To minimize your exposure to attack, delete any API keys that you no longer need.  You can delete API keys by using the DELETE /users/:id/api_keys/:key_id endpoint or on your Civis user profile on the bottom-right section of the page.
• Refresh your API keys periodically: You can refresh API keys by using the POST /users/:id/api_keys endpoint or on your Civis user profile on the bottom-right section of the page.  If you are calling the POST /users/:id/api_keys endpoint using an API key that has constraints, you will only be able to generate a new key with the same constraints.  You should delete your previous keys after obtaining new ones.
• Review your code before publicly releasing it: Ensure that your code does not contain API keys or any other private information before you make your code publicly available.

Additional Info

All of our documentation about API endpoints is located at https://platform.civisanalytics.com/#/api. There you can find the specifics about the input parameters and responses, as well as other basic API-related information.