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!
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
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:
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.
- 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.
- The “preflight” negotiation system used by CORS requires sending requests using the
OPTIONSHTTP 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:
- If you only need support for GETs, you can use JSONP instead.
- You can create a server-side proxy that interacts with the AgileZen API and returns data to your client application.