Session APIs

Session APIs

The Session service allows API clients to manage session tokens including creating, deleting and obtaining information about sessions.

  • The Session.create operation creates session token in exchange for another authentication token.
  • The Session.delete operation invalidates a session token.
  • The Session.get retrieves information about a session token.

The call to the Session.create operation is part of the overall authentication process for API clients. For example, the sequence of steps for establishing a session with SAML token is:

  • Connect to lookup service.
  • Discover the secure token service (STS) endpoint URL.
  • Connect to the secure token service to obtain a SAML token.
  • Authenticate to the lookup service using the obtained SAML token.
  • Discover the API endpoint URL from lookup service.
  • Call the Session.create operation. The Session.create call must include the SAML token.

See the programming guide and samples for additional information about establishing API sessions.

Execution Context and Security Context

To use session based authentication a client should supply the session token obtained through the Session.create operation. The client should add the session token in the security context when using SDK classes. Clients using the REST API should supply the session token using the vmware-api-session-id HTTP header field.

Session Lifetime

A session begins with call to the Session.create operation to exchange a SAML token for a API session token. A session ends under the following circumstances:

  • Call to the Session.delete operation.
  • The session expires. Session expiration may be caused by one of the following situations: = Client inactivity - For a particular session identified by client requests that specify the associated session ID, the lapsed time since the last request exceeds the maximum interval between requests. = Unconditional or absolute session expiration time: At the beginning of the session, the session logic uses the SAML token and the system configuration to calculate absolute expiration time.

When a session ends, the authentication logic will reject any subsequent client requests that specify that session. Any operations in progress will continue to completion.

Error Handling

The Session returns the following errors:

  • Unauthenticated error for any errors related to the request.
  • ServiceUnavailable error for all errors caused by internal service failure.

Operations
POST
Create Session
Creates a session with the API. This is the equivalent of login. This operation exchanges user credentials supplied in the security context for a session token that is to be used for authenticating subsequent calls. To authenticate subsequent calls clients are expected to include the session token. For REST API calls the HTTP vmware-api-session-id header field should be used for this.
DELETE
Delete Session
Terminates the validity of a session token. This is the equivalent of log out. A session token is expected as part of the request.
GET
Get Session
Returns information about the current session. This operation expects a valid session token to be supplied. A side effect of invoking this operation may be a change to the session's last accessed time to the current time if this is supported by the session implementation. Invoking any other operation in the API will also update the session's last accessed time. This API is meant to serve the needs of various front end projects that may want to display the name of the user. Examples of this include various web based user interfaces and logging facilities.