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
-
Navigate to the Bots tab of the Personal settings menu.
-
In the Actions column, click the manage bot
() icon,
and scroll down to API key.
-
Click the copy
() icon to
copy the bot's API key to your clipboard.
Anyone with a bot's API key can impersonate the bot, so be careful with it!
-
Go to Account & privacy.
-
Under API key, click Manage your API key.
-
Enter your password, and click Get API key. If you don't know your
password, click reset it and follow the instructions from there.
-
Copy your API key.
Anyone with your API key can impersonate you, so be doubly careful with it.
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.
-
Navigate to the Bots tab of the Personal settings menu.
-
In the Actions column, click the manage bot
() icon,
and scroll down to API key.
-
Click the generate new API key
() icon.
-
Go to Account & privacy.
-
Under API key, click Manage your API key.
-
Enter your password, and click Get API key. If you don't know your
password, click reset it and follow the instructions from there.
-
Click Generate new API key
Download a zuliprc file
-
Navigate to the Bots tab of the Personal settings menu.
-
In the Actions column, click the manage bot
() icon,
and scroll down to Zuliprc configuration.
-
Click the download
() icon
to download the bot's zuliprc file, or the copy
() icon to
copy the file's content to your clipboard.
Anyone with a bot's API key can impersonate the bot, so be careful with it!
-
Go to Account & privacy.
-
Under API key, click Manage your API key.
-
Enter your password, and click Get API key. If you don't know your
password, click reset it and follow the
instructions from there.
-
Click Download zuliprc to download your zuliprc file.
-
(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.
Anyone with your API key can impersonate you, so be doubly careful with it.
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 key |
Environment variable |
Required |
Description |
key |
ZULIP_API_KEY |
Yes |
The user's API key. |
email |
ZULIP_EMAIL |
Yes |
The email address of the user who owns the API key mentioned above. |
site |
ZULIP_SITE |
No |
URL where the Zulip server is located. |
client_cert_key |
ZULIP_CERT_KEY |
No |
Path to the SSL/TLS private key that the binding should use to connect to the server. |
client_cert |
ZULIP_CERT |
No* |
The public counterpart of client_cert_key/ZULIP_CERT_KEY. *This setting is required if a cert key has been set. |
client_bundle |
ZULIP_CERT_BUNDLE |
No |
Path 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. |
insecure |
ZULIP_ALLOW_INSECURE |
No |
Allows connecting to Zulip servers with an invalid SSL/TLS certificate. Please note that enabling this will make the HTTPS connection insecure. Defaults to false. |
Related articles