Imported Google Group message.
Sender:Martin Buhr.
Date:Tuesday, 11 August 2015 15:38:15 UTC+1.
Hi Richard,
Yes it is odd, but it harks back to some early changes we made to how Authentication and Authorisation are handled in Tyk, it’s not actually a work-around, it’s the way it’s supposed to be. deep breath:
Tyk separates out Authentication from Authorization, and has two different interfaces for this: AuthenticationHandler and SessionHandler, the first will confirm if a key is valid, while the other will only check if a key exists, a subtle difference I know, but nonetheless important. When Tyk sees a key in an inbound request, it queries the session handler for the key, if it doesn;t exist, it queries the authentication handler, if the auth handler returns the key, the session data is transferred to the session store for ongoing use until the key expires.
It is important to note that the Authentication handler and Session handler can have different storage back ends, in a default Tyk setup, theya are the same one (Redis), but they don’t have to be. This actually means that for any API, keys can be retrived from one back end, and all session maangmeent can be handled on a completely different one on a plug-and-play basis (you can configure it in the API Definition).
When Tyk creates a session (creates a key), it does so with the Session Handler, and since a key can exist across multiple APIs, and those APIs can have multiple Auth+Back-end / Session+Back-end combos, when we perform any operations on token, we need to know which back-end to use. When we have the sesison data, we know this from the actual access rights in the key, and if it’s a master key, then we actually write the key to all available session back ends (which is why we discourage their use).
However when retrieving a key, we need to know which back-end to use, and it isn;'t specified in the key itself, and so we require an API ID.
The whole API for the key management sits under the API resource, mainly to keep the interface sane, except for the key creation:
Get("/apis/:apiId/keys/search/", (*APIContext).SearchKeys).
Get("/apis/:apiId/keys/:keyId", (*APIContext).GetKeyDetail).
Put("/apis/:apiId/keys/:keyId", (*APIContext).UpdateKey).
Delete("/apis/:apiId/keys/:keyId", (*APIContext).DeleteKey).
Get("/apis/:apiId/keys/", (*APIContext).GetKeys).
Key creation:
Put("/keys/:keyId", (*APIContext).UpdateKey).
Post("/keys/", (*APIContext).CreateKey).
The problem is we left in the old PUT(!), and the documentation wasn’t updated to reflect the other changes, which is why it seems so incherent, but underlying it all is the requirement to be able to query different back-ends on a per-api basis.
Just a note on the separation of Auth/Session, if you have a separate authentication handler, you would never create a key in tyk, you would create them in your Authentication store (which Tyk does not control, only queries, e.g. Active Directory or your own User Store).
There’s an LDAP back-end bundled with the tyk gateway source as a PoC for this if you want to take a look actually, it’s a nifty feature - basically you could write your own authentication logic, AND hook up your own back end, the same goes for the session handler, or jsut drop in new back-ends for each with the default handlers, it’s quite flexible. The idea was for integrators to be able to customise Tyk to their own environments if needed without too much source-code surgery.
Hope that clarfies things a bit 
Cheers,
Martin