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

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. The preferred method is to set the custom X-PS-Api-Key HTTP request header: 

GET /psapi/v3/image/MY_IMAGE_ID?fields=image_id HTTP/1.1
Host: www.photoshelter.com
X-PS-Api-Key: MY_API_KEY
Alternatively, you can include your API key in the request URL with the api_key parameter: 
/psapi/v3/image/MY_IMAGE_ID?api_key=MY_API_KEY&fields=image_id

Authentication

If you would like to test member endpoints but do not currently have access to a PhotoShelter account, you can register for a free Trial Account. Trial Accounts have limited storage and theme options, but it will allow you to test the PhotoShelter API for up to 14 days. If you need an extension on the trial, reach out to our Technical Support team.

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.

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:

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

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 :

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

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.

The preferred method is to set the custom X-PS-Auth-Token HTTP request header:

GET /psapi/v3/mem/user/session HTTP/1.1
Host: www.photoshelter.com
X-PS-Auth-Token: MY_AUTH_TOKEN
X-PS-Api-Key: MY_API_KEY
Alternatively, you can include the token in the request URL with the auth_token parameter: 
/psapi/v3/mem/user/session?api_key=MY_API_KEY&auth_token=MY_AUTH_TOKEN