Manage Tokens

You can create persistent and non-persistent REST login tokens, view properties of tokens, and delete tokens. Properties of REST login tokens are read-only after the token is created. You can access a token via its returned token value or token ID.

Example 16-3 Creating a REST Login Token

Username and password are required to create a REST login token.

Set the token name. By default the value of preserve is false and the value of expiration is 900. If you set preserve to true, then you must set expiration to a number of seconds.

Be sure to save the value of X-Auth-Session from the result. For more information, see REST Login Tokens.

Example Request:

POST /api/user/v2/users/test_user/preferences/tokens HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-User: test_user
X-Auth-Key: password-xxx
Content-Type: application/json

{"name": "Test Token"}

Example Result:

HTTP/1.1 201 Created
...
X-Auth-Session: JjZJsZrVQfbZULyAuvSJjTftnBHCcQT

{
    "token": {
        "href": 
"/api/user/v2/users/test_user/preferences/tokens/fb65a127-a04c-4f58-bc52-efa884447efb", 
        "name": "Test Token",
        "token_username": "test_user",
        "preserve": false,
        "expiration": "2020-04-30T02:33:44Z",
        "id": "fb65a127-a04c-4f58-bc52-efa884447efb"
    }
}

Example Request:

POST /api/user/v2/users/test_user/preferences/tokens HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-User: test_user
X-Auth-Key: password-xxx
Content-Type: application/json

{"name": "Another Token", "preserve": true, "expiration": 3600}

Example Result:

HTTP/1.1 201 Created
...
X-Auth-Session: pviHrthBGQhGZHoPuqxFQrDcCPZgwEK

{
    "token": {
        "href": 
"/api/user/v2/users/test_user/preferences/tokens/21f981ad-6221-4fb4-a7d1-dd5560256dfb", 
        "name": "Another Token",
        "token_username": "test_user",
        "preserve": true,
        "expiration": "2020-04-30T03:20:31Z",
        "id": "21f981ad-6221-4fb4-a7d1-dd5560256dfb"
    }
}

Example 16-4 List All Tokens of the Specified User

Example Request:

GET /api/user/v2/users/test_user/preferences/tokens HTTP/1.1
X-Auth-Session: pviHrthBGQhGZHoPuqxFQrDcCPZgwEK

Example Result:

{
    "tokens": [{
        "name": "Another Token",
        "token_username": "test_user",
        "preserve": true,
        "expiration": "2020-04-30T03:20:31Z",
        "id": "21f981ad-6221-4fb4-a7d1-dd5560256dfb",
        "href": "/api/user/v2/users/testuser1/preferences/tokens/21f981ad-6221-4fb4-a7d1-dd5560256dfb"
    },{
        "name": "Test Token",
        "token_username": "test_user",
        "preserve": false,
        "expiration": "2020-04-30T02:33:44Z",
        "id": "fb65a127-a04c-4f58-bc52-efa884447efb",
        "href": "/api/user/v2/users/testuser1/preferences/tokens/fb65a127-a04c-4f58-bc52-efa884447efb"
    }]
}

Example 16-5 List a Specific Token by Its Token Value

Example Request:

GET /api/user/v2/users/test_user/preferences/tokens?token=pviHrthBGQhGZHoPuqxFQrDcCPZgwEK HTTP/1.1
X-Auth-Session: pviHrthBGQhGZHoPuqxFQrDcCPZgwEK

Example Result:

{
    "token": {
        "href": 
"/api/user/v2/users/test_user/preferences/tokens/21f981ad-6221-4fb4-a7d1-dd5560256dfb", 
        "name": "Another Token",
        "token_username": "test_user",
        "preserve": true,
        "expiration": "2020-04-30T03:20:31Z",
        "id": "21f981ad-6221-4fb4-a7d1-dd5560256dfb"
    }
}

Example 16-6 List a Specific Token by Its Token ID

GET /api/user/v2/users/test_user/preferences/tokens/21f981ad-6221-4fb4-a7d1-dd5560256dfb HTTP/1.1
X-Auth-Session: pviHrthBGQhGZHoPuqxFQrDcCPZgwEK

The result is the same as earlier.

Example 16-7 Delete a Token by Its Token Value

Example Request:

DELETE /api/user/v2/users/test_user/preferences/tokens?token=pviHrthBGQhGZHoPuqxFQrDcCPZgwEK HTTP/1.1
X-Auth-Session: pviHrthBGQhGZHoPuqxFQrDcCPZgwEK

Example Result:

HTTP/1.1 204 No Content

Example 16-8 Delete a Token by Its Token ID

DELETE /api/user/v2/users/test_user/preferences/tokens/21f981ad-6221-4fb4-a7d1-dd5560256dfb HTTP/1.1
X-Auth-Session: pviHrthBGQhGZHoPuqxFQrDcCPZgwEK