PhotoShelter Developer

Connecting to the PhotoShelter API

API Key

You need an API key to access any endpoint on the PhotoShelter API. It’s easy to register and use:

Step One: Register for an API key

An API key will be assigned to you automatically when you sign up.

Step Two: Include the API key in all requests

The API key should be included in every request you make to the API. One way to do this is by passing the api_key parameter in the request URL, like so:

/psapi/v3/image/MY_IMAGE_ID?api_key=MY_API_KEY&fields=image_id
Or, if you prefer not to pass the API key in every URL, you can set X-PS-Api-Key in the HTTP request headers:
httpChannel.setRequestHeader("X-PS-Api-Key", "MY_API_KEY", false);

Authentication

While the API key is sufficient for using any of our public endpoints, requests to our member endpoints require the client to be authenticated as a PhotoShelter user. If you would like to test member endpoints but do not currently have access to a Photoshelter account, you can register for a Starter Account for free.

The endpoint for user authentication is /psapi/v3/mem/authenticate. Calls to the authentication endpoint must be made via an HTTPS connection. There are two modes for authentication: cookie based and token based.

Cookie-based authentication

This is the default mode for user authentication, and the flow is easy to follow:

Step One: Direct your user to call our authentication endpoint

The user’s email and PhotoShelter account password need to be passed in the request, like so:

/psapi/v3/mem/authenticate?api_key=MY_API_KEY&email=me@example.com&password=supersecretpassword

Step Two: Include the HTTP cookie in the next call to a member endpoint

The cookie is of a proprietary format and should be sent as is. After authentication, each call to the API returns an updated HTTP cookie, which should be included in the subsequent request. This allows the API to accurately track idel time and manage your session.

Browsers can easily manage HTTP cookies, but if you are using the API outside of a browser environment, we recommend that you use token-based authentication.

Token-based authentication

The API also supports a token-based mode of authentication. This mode is recommended for use of the PhotoShelter API outside of a web browser environment, since the security token does not change throughout a session.

Step One: Direct your user to call our authentication endpoint

Pass the user’s email and PhotoShelter account password to the authentication endpoint, and set the parameter mode=token :

/psapi/v3/mem/authenticate?api_key=MY_API_KEY&email=me@example.com&password=supersecretpassword&mode=token

The server returns an authentication token in response.

Step Two: Send the token in all calls to member endpoints

The member endpoints accept the token to allow access. Tokens should be sent via an HTTPS connection to prevent it from being read in transit.

One way to pass the token is to set the parameter auth_token in the URL:

/psapi/v3/mem/image/MY_IMAGE_ID/delete?api_key=MY_API_KEY&auth_token=MY_AUTH_TOKEN

Alternatively, you can set X-PS-Auth-Token to the token value in the HTTP headers.

httpChannel.setRequestHeader("X-PS-Auth-Token", "MY_AUTH_TOKEN", false);