ContextQMD
Back to Zulip

API keys and `zuliprc` files

api_docs/api-keys.md

12.04.8 KB
Original Source

API keys and zuliprc files

An API key is how a user or bot can identify their account to Zulip.

A zuliprc file is a configuration file written in the INI file format, which contains key-value pairs, such as an API key and other configuration values, that are necessary for using the Zulip API with a specific user or bot account on a Zulip server, for example:

[api]
key=<bot API key>
email=<bot email address>
site=<Zulip server's URL>
...

For the official clients, such as the Python bindings, we recommend downloading a zuliprc file.

Get an API key

{start_tabs}

{tab|for-a-bot}

{settings_tab|your-bots}

  1. In the Actions column, click the manage bot (<i class="zulip-icon zulip-icon-user-cog"></i>) icon, and scroll down to API key.

  2. Click the copy (<i class="zulip-icon zulip-icon-copy"></i>) icon to copy the bot's API key to your clipboard.

!!! warn ""

Anyone with a bot's API key can impersonate the bot, so be careful with it!

{tab|for-yourself}

{settings_tab|account-and-privacy}

  1. Under API key, click Manage your API key.

  2. Enter your password, and click Get API key. If you don't know your password, click reset it and follow the instructions from there.

  3. Copy your API key.

!!! warn ""

Anyone with your API key can impersonate you, so be doubly careful with it.

{end_tabs}

Invalidate an API key

To invalidate an existing API key, you have to generate a new key. Generating a new API key will immediately log you out of this account on all mobile devices.

{start_tabs}

{tab|for-a-bot}

{settings_tab|your-bots}

  1. In the Actions column, click the manage bot (<i class="zulip-icon zulip-icon-user-cog"></i>) icon, and scroll down to API key.

  2. Click the generate new API key (<i class="zulip-icon zulip-icon-refresh-cw"></i>) icon.

{tab|for-yourself}

{settings_tab|account-and-privacy}

  1. Under API key, click Manage your API key.

  2. Enter your password, and click Get API key. If you don't know your password, click reset it and follow the instructions from there.

  3. Click Generate new API key

{end_tabs}

Download a zuliprc file

{start_tabs}

{tab|for-a-bot}

{settings_tab|your-bots}

  1. In the Actions column, click the manage bot (<i class="zulip-icon zulip-icon-user-cog"></i>) icon, and scroll down to Zuliprc configuration.

  2. Click the download (<i class="zulip-icon zulip-icon-download"></i>) icon to download the bot's zuliprc file, or the copy (<i class="zulip-icon zulip-icon-copy"></i>) icon to copy the file's content to your clipboard.

!!! warn ""

Anyone with a bot's API key can impersonate the bot, so be careful with it!

{tab|for-yourself}

{settings_tab|account-and-privacy}

  1. Under API key, click Manage your API key.

  2. Enter your password, and click Get API key. If you don't know your password, click reset it and follow the instructions from there.

  3. Click Download zuliprc to download your zuliprc file.

  4. (optional) If you'd like your credentials to be used by default when using the Zulip API on your computer, move the zuliprc file to ~/.zuliprc in your home directory.

!!! warn ""

Anyone with your API key can impersonate you, so be doubly careful with it.

{end_tabs}

Configuration keys and environment variables

The keys you can use in a zuliprc file (and their equivalent environment variables) can be found in the following table:

zuliprc keyEnvironment variableRequiredDescription
keyZULIP_API_KEYYesThe user's API key.
emailZULIP_EMAILYesThe email address of the user who owns the API key mentioned above.
siteZULIP_SITENoURL where the Zulip server is located.
client_cert_keyZULIP_CERT_KEYNoPath to the SSL/TLS private key that the binding should use to connect to the server.
client_certZULIP_CERTNo*The public counterpart of client_cert_key/ZULIP_CERT_KEY. *This setting is required if a cert key has been set.
client_bundleZULIP_CERT_BUNDLENoPath where the server's PEM-encoded certificate is located. CA certificates are also accepted, in case those CA's have issued the server's certificate. Defaults to the built-in CA bundle trusted by Python.
insecureZULIP_ALLOW_INSECURENoAllows connecting to Zulip servers with an invalid SSL/TLS certificate. Please note that enabling this will make the HTTPS connection insecure. Defaults to false.