Authentication Sessions

An authentication session ID is obtained from the access service by sending a POST request. This authentication session ID can be used by all other services as an identity credential. The authentication ID is invalidated after a timeout period set by the user’s session timeout property. The default is usually 15 minutes. A DELETE request can be used to logout and invalidate the session ID.

An authentication session is not required as clients can re-send authentication information with each request. Since the RESTful API operations are stateless, only the authentication ID is stored.

Login Session

An empty POST request requests a new login session. On success, an HTTP status of 201 is returned along with a JSON object that has a single property “access” that contains a list of available RESTful API services.

Example Login Request:

POST /api/access/v1 HTTP/1.1
Host: zfs-storage.example.com
X-Auth-User: root
X-Auth-Key: letmein-xxx

A successful login returns HTTP Status 201 (Created), as well as a session ID through the X-Auth-Session HTTP header. The response body contains a list of services accessible via this login.

Response Header:

HTTP/1.1 201 Created
X-Auth-Session: guigqpQRE4g89ngb
Content-Type: application/json
Content-Length: 378
X-Zfssa-Access-Api: 1.0

{
    "access": {
        "services":[{
            ...
        }]
    }
}

Logout Session

An empty DELETE sends a request to log out and invalidate the session.

Example Logout Request:

DELETE /api/access/v1 HTTP/1.1
X-Auth-Session: guigqpQRE4g89ngb  

Example Response:

HTTP/1.1 204 No Content
X-Zfssa-Access-Api: 1.0