Cashmere Link Guide (OAuth) Overview

This guide is for third-party applications that want to integrate Cashmere Link into their platform. Cashmere Link provides a seamless way for users to connect their licensed content collections to your application through an intuitive authorization interface powered by OAuth 2.0.

image.png

Cashmere Link is not an identity provider — it uses OAuth 2.0 purely as a secure way for users to grant scoped API access to their licensed content. The result of the flow is an API key, not a user profile.

  • Secure Authentication: OAuth 2.0 authorization code flow
  • Collection Authorization: Users can browse and select from their licensed collections
  • Instant API Access: Automatic API key generation for immediate content access
  • No User Identity or Profile Data: Cashmere Link does not provide user profile or identity information (e.g., name, email). It’s designed solely for secure, scoped access to Cashmere APIs

To integrate Cashmere Link into your application, you will:

  1. Register your application with Cashmere
  2. Implement the OAuth 2.0 flow
  3. Use the API key provided from the end of the OAuth flow to access Cashmere's content APIs

1.1 Contact Cashmere

To set up Cashmere Link for your application, contact Cashmere with the following information:

Required Information:

  • Application Name: Display name shown to users during authorization
  • Redirect URIs: List of valid OAuth redirect URIs for your application
  • Application Type: Web application, mobile app, or single-page application
  • Application Logo: The logo that will be shown to users

You'll Receive:

You configure your OAuth client with:

  • Credentials received from Cashmere (Client ID, Secret, Authorization Url, Access Token Url)
  • Grant Type: Authorization Code with PKCE (required)
  • Challenge Method: SHA-256
  • Redirect URI: Must match one of the Redirect URIs you provided Cashmere

Start the Cashmere Link experience by redirecting users to the authorization endpoint, typically after they have clicked a button like "Connect with Cashmere":

GET https://cashmere.io/o/authorize/

Required Parameters:

  • client_id: Your application's client ID
  • redirect_uri: One of your registered redirect URIs
  • code_challenge: PKCE code challenge (required)
  • code_challenge_method: Must be S256
  • scope: Must be empty or read, we do not support any other scopes and will error if you pass openid email profile etc. Either pass read or ensure your client does not pass default scopes that we do not support.

Example Authorization URL:

https://cashmere.io/o/authorize/?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

When users visit the authorization URL, they'll use Cashmere Link to login to Cashmere and browse and authorize collections.

image.png

image.png

After users complete selection and authorization in Cashmere Link, they're redirected back to your application with an authorization code:

https://yourapp.com/callback?code=AUTHORIZATION_CODE

2.4 Token Exchange

Exchange the authorization code for an access token (API key):

POST <https://cashmere.io/o/token/>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code_verifier=CODE_VERIFIER

Successful Response:

{
  "access_token": "your-api-key",
  "token_type": "Bearer",
  "expires_in": 3153600000,
  "refresh_token": "refresh-token",
  "scope": "read write collections:1,2,3,4"
}

The access_token is a Cashmere API key and can be used to access Cashmere's APIs. You should save this key and associate it with your user accounts. API keys do not expire, but we return a high expires_in value as well as a refresh_token to fully meet the OAuth 2.0 specification.

Step 3: Using Your API Key

With a valid API key, you can access the Cashmere API

https://cashmere.io/api/v2/docs

GET https://cashmere.io/api/v2/search
Authorization: Bearer your-api-key
Content-Type: application/json

4.1 Direct Publisher URL

Link can be configured to go straight to a specific publishers’ collections. Users still have the option to browse to and select collections from other publishers

https://cashmere.io/o/authorize/?linkPublisher={{publisher_id}}

Cashmere Link supports a "Short Link" mode for ultra-streamlined experiences. Users authenticate directly with a publisher's OAuth provider, then return to Link with their collections pre-selected based on their publisher account permissions. Publishers must perform extra steps to set this up. Users do not have the option to browse or select collections from other publishers.

This is best for publishers that already have their own login, subscription, or user management system, and they want to synchronize their authorization and entitlement settings with Cashmere.

image.png

Additional steps are outlined here:

After completing the steps initiate the same Link flow as before with your publisher_oauth_provder_uuid included in the authorization url:

https://cashmere.io/o/authorize/{{publisher_oauth_provider_uuid}}