Why?

Housecarl AuthZ is an API server for authorization questions.

Essentially, once you have a username that you have confirmed is valid, you need to know what that username can do. That question is what Housecarl AuthZ answers for you.

The process looks roughly as follows:

• Get a Housecarl AuthZ server configured for your application (See the Configuration Guide).
• Get an API key for a service account
• POST the question to /api/v1/tenant/allow and recieve the response as a JSON bool.

Of course, the angel is in the details of what, specifically, constitutes a valid question.

The question is formulated as a JSON object: { "context": { "key": "value", ... } }

The context map must have a set of keys: This will represent the entity your code is inquiring about:

• "subject": "etc"

This will represent the attempted action. Plausibly, this will be an API method.

• "action": "something or other"

This is what the subject wants to action on -

• "object": "hc://domain/:uuid/path/to/resource".

The Configuration Guide will provide more information, but in short, an object is a specific kind of URI. The UUID value denotes the "domain" the specific resource is under. These "domains" are not internet domains qua the "Domain Name System", but represent an enterprise specific collection of resources of a certain kind or class. Permissions are associated with domains, and domains can inherit from other domains. This allows complex and useful layering of permissions.