You're viewing documentation for version 3. Find version 4 here.

PhotoShelter Developer

User Authentication and Session Management

The PhotoShelter API allows users to access their accounts and make changes, like uploading an image or deleting a gallery. Access to these member endpoints requires user authentication (along with the API key, which is always mandatory). This guide explains how to authenticate a user and manage sessions on the API.

What you need

What you should know

You can choose to use either cookie-based or token-based authentication. Using HTTP cookies is the default mode and can be easily managed in a browser environment. If your application is designed to run in a non-browser environment, however, token-based authentication is recommended to simplify session management.

Don't forget, calls to the authentication endpoint must be made via an HTTPS connection.

What to do

Initial authentication

Let’s say that the user account email is “me@example.com” and the password is “supersecretpassword”. To authenticate the user, simply pass the email and password to the endpoint /psapi/v3/mem/authenticate. If you want to use token-based authentication, also pass the mode parameter in your request.

Cookie-based Token-based
Example auth request POST /psapi/v3/mem/authenticate HTTP/1.1
Host: www.photoshelter.com
X-PS-Api-Key: MY_API_KEY

email=me@example.com&password=supersecretpassword 		POST /psapi/v3/mem/authenticate HTTP/1.1
Host: www.photoshelter.com
X-PS-Api-Key: MY_API_KEY

email=me@example.com&password=supersecretpassword&mode=token
What’s returned HTTP cookie Authentication token

After authenticating, the user is free to use any of PhotoShelter API’s member endpoints.

Organization authentication

Some users may belong to an organization (an MU or Libris account). Authenticating as the member of an organization requires an additional step. If the user belongs to any organizations, the response to /psapi/v3/mem/authenticate will include an org object containing their organization ID(s). Use that ID with the /psapi/v3/mem/organization/{organization_id}/authenticate endpoint to authenticate as a member of that organization. A user may only be authenticated to one organization at a time.

Session management

Sessions are managed a little differently between cookie-based mode and token-based mode.

In a browser environment, the browser handles sending the cookie along with your request to the PhotoShelter API. Each time you make a request to the API, it returns a new cookie in order to accurately track idle time. By default, the browser simply replaces the old cookie with the new one, and takes care of sending the newest cookie the next time you make a request.

Token-based

Because the PhotoShelter API returns a new HTTP cookie with each response, tracking and sending the most up-to-date cookie can become tricky in a non-browser environment. In this case, using token-based authentication becomes easier to handle, since the authentication token remains constant throughout a session.

To access a member endpoint, simply include the authentication token with your request. You can choose to set X-PS-Auth-Token to the token in the HTTP headers (preferred), or you can set auth_token=MY_TOKEN in the request URL. Be sure to use an HTTPS connection when sending the token.

Examples available in the Connecting to the PhotoShelter API guide.

Logout

To log out of the account, simply send a request to the endpoint /psapi/v3/mem/authenticate/logout, and the user’s session will be closed.

Further Reading