AgileZen API Documentation

Authentication

API Keys

AgileZen uses API keys to associate requests with the users that are making them. API keys are identified by a token, which is just a unique series of letters and numbers. Anyone can create an API key via the Developer tab on the Settings screen, and you can have as many keys as you like. Keys can be enabled and disabled as necessary, and all requests using a given key will be denied while the key is disabled.

You should typically create a separate API key for each integration that you use with AgileZen. That way, you can control access to the different integrations independently of one another.

An API key authenticates you on AgileZen, just like a username and password. If someone intercepts your API key, they won't be able to log in to your account, but they will be able to make API calls on your behalf. Treat API keys as passwords and protect them accordingly!

Authenticating Requests

All requests to the AgileZen API must include a valid and enabled API key in order to be processed. To specify which key to use in a request, set it as the value of the HTTP header X-Zen-ApiKey.

For example, if your key’s token is 9aae75efd6b3470db8abd15b61c55cef, your request might look like:

GET /api/v1/projects
...
X-Zen-ApiKey: 9aae75efd6b3470db8abd15b61c55cef
...

It’s strongly recommended that you use the X-Zen-ApiKey HTTP header to specify your key, but if for some reason you’re unable to set headers, you can also pass your key via the apikey argument. For example:

https://agilezen.com/api/v1/projects?apikey=9aae75efd6b3470db8abd15b61c55cef

SSL Encryption

All requests to the AgileZen API must be done over HTTPS. Regardless of whether or not your account supports SSL encryption, you can (and must) access the API via HTTPS. If you make a request on a non-encrypted HTTP channel, AgileZen will return an HTTP redirect (302) pointing to the secure endpoint.

Cross-Origin Resource Sharing

AgileZen’s API also supports the draft specification of Cross-Origin Resource Sharing (CORS). This technology provides for secure communications not subject to the same origin policy to which XMLHttpRequest (XHR) calls are normally held.

The primary reason to use CORS is to create a JavaScript-only client that interacts with the AgileZen API. The experience should be handled in a seamless fashion, but please be aware of two limitations:

  1. Only newer browsers (Firefox 3.5+, Internet Explorer 8+, Safari 4+, Chrome 3+) have support for CORS negotiation. Requests will silently fail on older browsers.
  2. The “preflight” negotiation system used by CORS requires sending requests using the OPTIONS HTTP verb. This may cause problems behind some overeager proxy servers and firewalls.

If you can’t be restricted by these limitations, you have two options:

  1. If you only need support for GETs, you can use JSONP instead.
  2. You can create a server-side proxy that interacts with the AgileZen API and returns data to your client application.

For an in-depth explanation of CORS, please see the HTTP Access Control article on the Mozilla Developer Network. The draft specification for CORS is also available on the W3C site.