The TwentyThree API uses the OAuth 1.0a protocol for user authorization and application identification.

Generally, some requests can be made anonymously, but whenever your application needs to read unpublished data or update or add new data, authentication is required. This is done by setting up consumer key and a consumer secret for you application, and then by having an existing user authorize your access. When this is done, you'll have an additional access token and am access token secret which will be used alongside your consumer credentials to sign all requests.

All interaction with the OAuth authentication process in done through a generic domain, https://api.visualplatform.net/oauth/*, or through your site's own domain, https://videos.example.com/oauth/*.

You can find more information on how to use OAuth 1.0a with the TwentyThree API in the OAuth set-up and flow document. Please refer to this document if you at all unsure about how to use OAuth with this API.

Anonymous access

A number of the API endpoints allow anonymous access to the public data from public sites. For example, a request to /photo/list will yield a list of published videos of the site including information on how to play and embed these videos.

Of course, unpublished content on public sites and any content on non-public sites will not be available to anonymous API calls. For more information about access and permission levels, refer to the next section.

Token access to photos and videos

In general terms, access to videos can be controlled through an identifier (photo_id) and a shared secret (token). Using a combination of these two, you will always be able to retrieve the full URL of an object. This method can be used to grant access to unpublished or hidden videos to select users, for example through an embed code.

• On publicly accessible sites, both the photo_id and token of any published video is freely available through the API.
• On closed sites, tokens on published videos are available to visitors with their sessions signed.
• All tokens (including those to non-published videos) are available to logged-in users. This also means that the token for unpublished items is not available to the public without it having been explicitly shared.

Put plainly: If a token is shared, a user will always have access to an item. When a video is made public, the token is too.

Permission levels

The API operates with a set of different permission levels. At each level, some actions are allowed and some are prohibited:

• Permission level none: You are given no access to the API. At this level, you will need specific information such as album_id or photo_id plus a secret token to access data. This level is usually only applied when a sites is closed to the public and the client hasn't been authenticated in any way.
• Permission level anonymous: The client has access to publicly available data. The is the default access level on a public site. On a non-public site, the permission level is only given to clients logged in through the standard cookie login mechanism (which isn't part of the API).
• Permission level read: Access at this level can be granted through the OAuth authentication process. At this level, both public and private data is available through the API.
• Permission level write: Access at this level can be granted through the OAuth authentication process and will allow the API to both add new objects (i.e. uploading video) and delete existing ones.
• Permission level admin: Access at this level can be granted through the OAuth authentication process and will allow the API to perform administration actions such as creating new users.
• Permission level super: Access at this level can only be obtained by keys and tokens created by the site owner setting up privileged credentials in a site's backend. Using these credentials, the API will be able to log in users and sign client sessions.

The levels are listed in ascending order, meaning that super authentication will give access to all lesser levels as well, and a client with read will also have anonymous and none rights.

How these rules are applied to methods is detailed under the individual method documentation. Whenever a request is denied due to lack of permissions, an error message is return detailing both the client's actual level and the level necessary:

{
    "status": "error",
    "message": "You don't have the necessary permissions to perform this action (required level: 'write')",
    "code": "permission_denied",
    "permission_level": "none"
}

Any request to the API will also list the client's permission level in the response attributes. For example:

{
    "status": "ok",
    "permission_level": "admin",
    "cached": false,
    "p": 1,
    "size": 500,
    "total_count": 6,
    "data": [...]
}

Caching

Anonymous requests to the API may be cached for performance reasons. This means that responses can be cached for a period of up to 30 minutes. Signed requests to the API are never cached.

Cached responses will have cached=1 set in the response:

{
    "status": "ok",
    "permission_level": "anonymous",
    "cached": true,
    "p": 1,
    "size": 20,
    "total_count": 6,
    "cache_time": 1712309346,
    "data": [...]
}

The extra property cache_time notes when the content of the response was originally cached in seconds since epoch.

For performance reasons, we ask you to use the cached version of any request, but you will be able to ask for a non-cached version of a response either by signing your requests or by adding a ?time=<current_timestamp> parameter to your request.