When you create your authentication provider, you will define how the user token is created, including roles for the given user, additional properties about that user, and the lifetime of the key that is generated:
return {
errorMessage: null, // Indicates success
roleNames: ['role1', 'role2'], // This cannot be empty, otherwise the user will have no permissions
userData: { employeeId: "12345", region: "US-West"}, // Optional: these properties will be attached to the API key
userInfo: { email: "jdoe@acme.com" }, // Optional: these properties will be returned along with the API key
keyLifetimeSeconds: 3600, // How long the API should be valid for, 0 for perpetual
lastLogin: new Date(2013, 11, 31), // Optional: last time user logged in (caution: JS Date has 0-based month)
lastLoginIP: "12.34.56.78" // Optional : the IP from which the user last logged in
};
When the user logs in, your application will call the @authentication endpoint, which will return an auth token in the following form:
> curl -d @authrequest.json -H "Content-Type: application/json" http://localhost:8080/rest/default/api/v1/@authentication
{
"apikey": "aaea381a23f2c3289dda59f47cf450bc",
"expiration": "2017-10-09T23:43:30.941Z",
"lastLoginTs": "2017-10-05T23:34:09.867Z",
"lastLoginIP": "0:0:0:0:0:0:0:1"
}
That auth token must be submitted along with subsequent API requests by the client application (in an Authorization header or as a URL parameter). On the API Server side, it remembers that user session, manages timeouts, etc. When the next call comes in, it will look up the user information based on the auth token, see if the token is still valid, and if so, allow the request.
Let me know if this is clear.
-Jaime