Authentication

The DiapStash API uses OAuth 2.0 for user authentication. This allows you to retrieve authentication tokens for each user of your service. Authentication via OAuth 2.0 will automatically redirect users to their DiapStash account login page. At no time will you have access to their personal information (email, username, and password).

OAuth 2.0 Server Configuration

OAuth 2.0 server configuration information (endpoints, supported scopes, authentication methods, etc.) is available at:

https://account.diapstash.com/.well-known/oauth-authorization-server

This URL returns a JSON document compliant with RFC 8414 containing all the metadata needed to configure your OAuth 2.0 client.

Main Endpoints

• Authorization Endpoint: https://account.diapstash.com/oidc/auth
  Used to initiate the authentication flow and obtain user consent
• Token Endpoint: https://account.diapstash.com/oidc/token
  Used to exchange an authorization code for tokens, or to refresh an access token

Registering Your Application

To obtain authentication tokens, you must first register your application as an API client at https://account.diapstash.com in the "API Access" tab.

Once your client is registered, you will receive:

• A Client ID (required)
• A Client Secret (depending on your application type)

These credentials are necessary for OAuth 2.0 authentication.

Allowed Origins (CORS)

If your application calls OIDC endpoints directly from a browser (e.g. a SPA exchanging tokens at the token endpoint), you must declare the allowed origins of your application.

In the client settings on account.diapstash.com, fill in the Allowed Origins field with each origin that is allowed to make cross-origin requests to the OIDC endpoints. Each entry must be a full origin URL without a trailing slash (e.g. https://myapp.com).

Scopes (Permissions)

Scopes allow you to precisely define the permissions your application requests. During OAuth 2.0 authentication, you must specify the scopes you need. Users will be informed of the data your application wishes to access before authorizing your application.

Available Scopes

Access Token & Refresh Token

OAuth 2.0 authentication returns two types of tokens:

Access Token

• Provision: Automatically provided during authentication
• Lifetime: 1 hour after generation
• Usage: Must be passed in the header of each API request to authenticate the call (see Api Usage page)

Refresh Token

• Provision: Must be explicitly requested (see below)
• Lifetime: 14 days
• Usage: Allows obtaining a new access token without asking the user to reauthenticate
• Important:
  • It is renewed at the same time as the access token
  • It can only be used once
  • Once used, a new refresh token is generated

Obtaining a Refresh Token

To obtain a refresh token, you must:

1. Include the offline_access scope in your authorization request
2. Add the prompt=consent parameter during the OAuth 2.0 flow

Authorization request example with prompt=consent:

https://account.diapstash.com/oidc/auth?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=cloud sync.history cloud sync.types offline_access
  &prompt=consent

Authentication Flow

1. Redirect to Authorization Endpoint

Redirect the user to the DiapStash authorization endpoint with the required parameters (client_id, redirect_uri, response_type, scope, etc.).

2. User Authentication and Consent

The user logs into their DiapStash account and grants permission for your application to access their data according to the requested scopes.

3. Authorization Code Callback

DiapStash redirects the user back to your redirect_uri with an authorization code in the query parameters.

4. Exchange Authorization Code for Tokens

Make a POST request to the token endpoint to exchange the authorization code for an access token (and optionally a refresh token if offline_access scope and prompt=consent params were requested).

5. Use Access Token

Include the access token in the Authorization header of your API requests to authenticate calls to the DiapStash API.

6. Refresh Access Token

Before the access token expires (1 hour), use the refresh token at the token endpoint to obtain a new access token and refresh token.

PKCE (Proof Key for Code Exchange)

PKCE is an OAuth 2.0 security extension that protects against authorization code interception attacks.

Usage:

• Mandatory for web applications (SPA - Single Page Applications)
• Strongly recommended for native mobile applications

How It Works

1. Generate a code_verifier: random string of 43 to 128 characters
2. Generate the code_challenge: BASE64URL(SHA256(code_verifier))
3. During authorization, add the parameters:
   • code_challenge=YOUR_CODE_CHALLENGE
   • code_challenge_method=S256
4. When exchanging the code, send the original code_verifier

The server will verify that the code_verifier matches the code_challenge before issuing tokens.

Security

• Never share your Client ID and Client Secret
• Store tokens securely
• Use HTTPS for all communications
• For web and mobile applications: Use PKCE (Proof Key for Code Exchange) to protect the authorization flow against interception attacks. PKCE is particularly recommended for Single Page Applications (SPA) and native mobile applications.