OAuth 2.0 Authentication

OAuth 2.0 is an industry-standard authorization protocol that allows third-party applications to access Napkin resources on behalf of users without requiring them to share their credentials. Instead of sharing passwords, users authorize your application through a secure consent flow, granting limited access based on specific scopes.

This is ideal for building integrations, plugins, or applications that need to generate visuals or access user data from Napkin.

Application Approval Required

To use OAuth 2.0, your application must be approved by the Napkin.ai team. Please contact us to register your application and obtain client credentials.

Available Scopes

Scope	Description
user	Access to basic user profile information (email, name, user ID)
generation	Ability to create visual generations on behalf of the user

OAuth Flow

1. User clicks "Connect with Napkin" in your application
2. User is redirected to Napkin's authorization page
3. User logs in and approves access to your application
4. Napkin redirects back to your app with an authorization code
5. Your server exchanges the code for access and refresh tokens
6. Use the access token to make API requests on behalf of the user

Step 1: Authorization Request

Redirect users to the Napkin authorization endpoint:

GET https://api.napkin.ai/v1/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=user%20generation
  &state=RANDOM_STATE_VALUE

Parameter	Required	Description
client_id	Yes	Your application's client ID
redirect_uri	Yes	URL-encoded callback URL (must match registered URIs)
scope	No	Space-separated scopes (URL-encoded). Defaults to user
state	Recommended	Random string to prevent CSRF attacks

Step 2: User Authorization

The user logs in to Napkin and grants permission to your application.

Sign in screen

Consent screen

Step 3: Authorization Code

After authorization, the user is redirected to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=AUTH_CODE&state=RANDOM_STATE_VALUE

tip

Always verify the state parameter matches what you sent to prevent CSRF attacks.

Step 4: Exchange Code for Tokens

Exchange the authorization code for access and refresh tokens:

curl -X POST https://api.napkin.ai/v1/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

Success Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "scope": "user generation"
}

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token:

curl -X POST https://api.napkin.ai/v1/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Single-Use Refresh Tokens

Refresh tokens are single-use. Each time you refresh, you receive a new refresh token. The old refresh token is automatically revoked.

Revoking Tokens

Revoke an access or refresh token when it's no longer needed:

curl -X POST https://api.napkin.ai/v1/oauth/revoke \
  -d "token=ACCESS_OR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Returns 200 OK on success (per RFC 7009, always returns 200 regardless of token validity).

Token Expiration

Token Type	Expiration
Access Token	1 hour
Refresh Token	30 days
Authorization Code	10 minutes

Using Access Tokens

Once you have an access token, use it to authenticate API requests by including it in the Authorization header as a Bearer token.

Making API Requests

Include the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Generating Visuals

To generate visuals on behalf of the user, make a POST request to the /v1/visual endpoint:

curl -X POST https://api.napkin.ai/v1/visual \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"format": "svg", "content": "Your text content here"}'

The access token must have the generation scope to create visuals. See the Create Visual Request endpoint documentation for full details on request parameters and response format.

Error Responses

OAuth Token Endpoint Errors

These errors are returned by the /v1/oauth/token endpoint when exchanging or refreshing tokens:

Error Code	Description
invalid_request	Missing or invalid parameter
invalid_client	Invalid client credentials
invalid_grant	Invalid/expired authorization code or refresh token
unsupported_grant_type	Grant type not supported
invalid_scope	Requested scope not allowed for this application
access_denied	User denied authorization or is not logged in

Example Error Response:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

API Request Errors

When using access tokens to make API requests, the following HTTP status codes may be returned:

HTTP Status	Error Message	Description
401 Unauthorized	OAuth access token has expired. Please refresh your token using the refresh_token grant.	The access token has expired. Use the refresh token to obtain a new access token.
401 Unauthorized	OAuth token has been revoked	The token has been revoked. The user needs to re-authorize your application.
403 Forbidden	Various	The request is forbidden due to invalid credentials or other authorization issues.

Handling Expired Tokens

When you receive a 401 Unauthorized response with the message indicating the token has expired, use your refresh token to obtain a new access token. Implement proactive token refresh before expiration to provide a seamless user experience.

Best Practices

• Always use the state parameter — Prevents CSRF attacks
• Validate redirect URIs — Only use registered redirect URIs
• Keep client secrets secure — Store them securely and never expose in client-side code
• Request minimal scopes — Only request scopes your application needs
• Handle token expiration — Implement automatic token refresh before expiration