The API will be made accessible through the provision of API keys, private or public.
There are a number of possible approaches to API key generation i.e. random numbers, UUIDs etc. This package does a good job of creating random, readable API keys.
Private API keys are for server-to-server usage only and should never be publicly accessible.
Similar to passwords, private API keys are secret and should only ever be stored as hashed values, not in plaintext. In the event of a lost or compromised secret key, organizations will be able to generate a new secret key.
Public API keys are for client-to-server usage only and are assumed to be publicly accessible.
To restrict access to permitted clients only, the public API key should be stored with a list of white-listed domains which are permitted to make requests to the API using that key. All other domains should be blocked from making requests.
Publication
A collection of articles contributed and maintained by one or more creators for the purpose of thematic arrangement, unified identity or editorial standard e.g. blogs, newsletters etc.
Organization
An aggregator of and platform for hosting publications and articles e.g. Medium, Substack, The New York Times. Organizations are the third party consumers of the Audyo API.
Organization Admin
A user that represents and can take administrative actions on behalf of an Organization. Organization users can generate and regenerate API keys.
Organization Creator
A creator and publisher of content on an Organization’s platform. Organization creators can access the Audyo creator portal to enhance their own audio content.
Organization End User
A consumer of content that is published on an Organization’s platform i.e. a reader or listener.
Organization Admins have the ability to generate Audyo API keys in the Audyo web app. The private key is only viewable once and should be stored safely by the Organization.
The secret key is hashed and stored in the Audyo database.
In the event of a lost or compromised secret key, Organization Users can regenerate their secret API key.
The old API key will be revoked and requests made using this key will no longer be permitted by the API.
In future, the user will be able to select a delayed revocation, allowing them time to update requests to use the new key. During this period, requests using both the old and new keys will be permitted by the API. After this grace period, the old key will be fully revoked and requests using this key will no longer be permitted by the API.
Organization Creator’s should be able to add Audyo to their post as part of their standard publishing flow.
When a Creator wants to add Audyo to a Post, an authenticated request is made to the Audyo API with a publicly accessible URL for the post.
The request also carries the Organization User ID and Organization Publication ID (if applicable). There will be middleware in place to check if the external user ID has been seen before and is associated with an existing Audyo User. If not, a new Audyo shell User is created (with no email, name or username). Similarly for previously unseen Publications. Ideally we would also receive some User information here such as email, name, username but this will require explicit user consents (most likely through a full OAuth flow).
An asynchronous Audyo pipeline process is triggered which, on success, produces a playable audio version of the submitted content.
The Audyo API responds immediately to the request with a Player URL and Player ID which should be persisted by the 3rd Party's server and associated with the submitted Post. The Player ID is a 'pseudo' ID as the player entity is not created until the Audyo generation has fully completed. However, this is the ID that will be used to identify the Player when it is created. The Third Party consumer of the API does not require any knowledge about the Player state as this will be handled entirely by the Player page as explained in detail below.
A webhook URL can also be provided to inform the 3rd Party when the Audyo has finished generating to allow for notifications, email updates, etc.
The Audyo for a Post will be accessible via the Player URL returned by the Audyo API at the time of the initial request. The player URL will present differently depending on the state of the Audyo.
When the audio has successfully finished generating, the Player page will present with the standard Audyo player.
Before the audio has finished generating, the page will present with a “Audyo Generating” state (designs outstanding) and possibly some indication of progress.
If something went wrong during the generation of the audio, the page will present with a "Did Error" state (designs outstanding).
Organization Creators should be able to directly access the Audyo creator portal to enhance the Audyo for their content. In order to make the transition from the organization’s site to the creator portal as seamless as possible, we should avoid requiring the creator to manually login.
To do this, the organization server will have to “login” on behalf of the creator using the API key and organization user ID. The Audyo API will respond with a link to the Post Editor in the Creator Portal, including the access token as a query parameter.
The external API is proposed to use REST rather than GraphQL. REST has more widespread adoption and is therefore easier for third parties to integrate in general. Also, as the API has very lightweight responses, there would be limited benefit to using GraphQL at this time.
The new internal endpoints (for use exclusively in the creator portal) will be GraphQL in line with the existing internal API.
createOrganization- Params:
name - Response:
Organization
- Params:
updateOrganizationDetails- Params:
organizationId,name - Response:
Organization
- Params:
generateOrganizationApiKey- Params:
organizationId - Response:
apiKey
- Params:
regenerateOrganizationApiKey- Params:
organizationId,revokeImmediately - Response:
apiKey
- Params:
addOrganizationWebhookUrl- Params:
webhookUrl - Response:
message
- Params:
POST /audyo- Basic Auth:
username:password=$API_KEY: - Headers:
Organization-User-Id,Organization-Publication-Id - Params:
url - Response:
playerUrl,playerId
- Basic Auth:
GET /audyo/players/:playerId/editor_url- Basic Auth:
username:password=$API_KEY: - Headers:
Organization-User-Id,Organization-Publication-Id - Response:
editorUrl
- Basic Auth:
OrganizationidnamehomepageUrlcreatedAtupdatedAt
OrganizationMemberidorganizationIduserIdcreatedAtupdatedAt
OrganizationApiKeyidorganizationIdpublicKeysecretKeystatus- [LIVE,REVOKED]createdAtupdatedAt
OrganizationUserMappingidorganizationIdaudyoUserIdorganizationUserIdcreatedAtupdatedAt
OrganizationPublicationMappingidorganizationIdaudyoPublicationIdorganizationPublicationIdcreatedAtupdatedAt
OrganizationWhitelistedDomainidorganizationIddomaincreatedAtupdatedAt