Authentication
The API uses HTTP Basic authentication (username/password) for each request. There is no concept of session or token like other HTTP APIs you may have used before because of the simplicity of this implementation -- it's unlikely you'll be making more than one or two requests at a time. This also allows you to more easily make certain API calls directly in a browser, or (if your client supports it) via a URL using the (deprecated) URL-embedded authentication (e.g. https://<user>:<password>@api.netfire.com/waf/v1/{tenant}/).
Most client libraries support HTTP Basic authentication natively, but if you are unable to use it for some reason it is simple enough to do yourself. Assuming a user alice with password examplepassword:
- Start by combining the username and password with a colon; the ordering is important. (e.g.:
alice:examplepassword) - Then encode this string as Base64 (e.g.
YWxpY2U6ZXhhbXBsZXBhc3N3b3Jk) - Finally, pass this value as part of an
Authorizationheader with your API request/call (e.g.Authorization: Basic YWxpY2U6ZXhhbXBsZXBhc3N3b3Jk)
If authentication fails or no authentication was provided, an HTTP 401 Unauthorized status will be returned.
Authorization
Authorization is performed via your NetFire-managed Active Directory domain. By default even if a user specifies a valid username/password for your AD domain, no actual permissions are granted except HEAD requests (which are only useful to determine the status of the API server, validity of a request's URL, etc. but no real data is returned or written).
Groups are used to specify which Active Directory groups should be granted access to which permissions.
NetFire manages your access groups for you.
To manage access to staff groups in your organization, please contact support by emailing [email protected] or submit a request directly to our help desk.
If authorization fails, an HTTP 403 Forbidden status will be returned.
Permissions
Administrators of your organization can specify very fine-grained control over which staff members have access to which operation. For reference, these are the associated operations and what that permission allows.
| Operation | Description |
|---|---|
| Create Host | Grants permission to create new hosts under the tenant. |
| Read Host | Grants permission to get details about current host configurations. Likely you will also want to enable List for users with Read. If a host is specified, only return information about that specific Host; otherwise return information for all existing ones. |
| Update Host | Grants permission to update existing hosts but not create new ones. Partial updates are supported, but a HostID cannot be modified once created -- it would need to be deleted and recreated with the new HostID. |
| Delete Host | Grants permission to remove a host definition for your tenant. |
| List HostIDs | Grants permission to view the names/HostIDs of currently defined hosts (but not their details unless Read is also granted). |
If authorization fails due to an unsupported method for an operation's URL, an HTTP 405 Method Not Allowed status will be returned.