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

  • An API key with PhotoShelter, which is required to access the API. To run the example code in this guide, replace "MY_API_KEY" with your own key. Register for an API key.
  • Access to a PhotoShelter account. If you don't have one, you can sign up for a free Starter Account. Starter Accounts have limited storage and theme options, but it will allow you to test the PhotoShelter API.

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 “” 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
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.


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 auth_token=MY_TOKEN in the request URL, or you can set X-PS-Auth-Token to the token in the HTTP headers. Be sure to use an HTTPS connection with sending the token.


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