# How to create an OAuth app in Digits

Before you get started, make sure you have a [Digits developer account](https://my.digits.com/join/developer).

## 1. Create your OAuth app

Log in to your Digits account and navigate to the **Developer** section in the left sidebar.

Click **Create App** to start the app creation process.

## 2. Identity settings

Configure your app's identity information:

- **App Name**: Enter a meaningful name that your users will see during authorization (e.g., "Your Company - Accounting Integration")
- **Tagline**: A brief description of your app's purpose
- **Icon**: Upload an app icon - this appears on the Developer Dashboard and the install/auth screen

Your icon is the first thing users see, so choose something that builds trust and represents your brand.

## 3. Summary details

Fill in your app's summary information:

- **Description**: Explain what your app does and how it integrates with Digits
- **Homepage URL**: Your company website or SaaS product URL (must begin with `https://`)
- **Support Email**: Where users can reach you for help
- **Developer Contact Email**: For Digits to contact you about your app

## 4. Redirect URL configuration

In the Configuration section, set up your redirect URLs.

Add the following redirect URL:

```
https://unify.apideck.com/vault/callback
```

**Important notes:**
- Redirect URLs must be complete URLs
- Production redirect URLs must use `https://` (`http://` is accepted only for `localhost`)
- No wildcards or fragments are allowed
- IP addresses are not permitted (except `localhost` for local development)
- The redirect URI must **exactly match** your registered URI for OAuth to work

## 5. Configure scopes

> **Settle your scopes before you copy your credentials in step 6.** Digits sets scopes as part of the Create App flow, and changing them afterwards may require your users to re-authorize and may require regenerating your credentials - which would invalidate a Client Secret you had already saved in Apideck.

Digits offers three permission scopes:

| Scope | Description |
|-------|-------------|
| `source:sync` | Write ledger data to Digits |
| `ledger:read` | Read ledger data from Digits |
| `documents:write` | Upload and manage documents |

The Apideck Digits connector requests only `ledger:read`, so selecting that single scope covers every call Apideck makes on your behalf. Add `source:sync` or `documents:write` only if your own application calls Digits directly for those purposes.

**Best practice**: Apply the principle of least privilege - request only the scopes your app actually needs.

## 6. Get your credentials

Navigate to the **Keys** tab to find your client credentials. A toggle at the top of the page switches between the **Development** and **Production** key sets, and each set has its own Client ID and Client Secret.

Which set you use depends on whose ledger you need to reach. Digits governs that with four app modes rather than a simple test/live switch - the Keys toggle only decides which credentials you send, the mode decides where the app can be installed:

| You want to connect | Mode | Keys | Digits approval |
|---|---|---|---|
| Your own Developer Sandbox, for testing | Development | Development | None - every app has Development keys from the moment it is created |
| Your own Digits entities, or the clients of your own firm | Internal | Production | None, as long as the installer has access to both the app and the target entity |
| Any other Digits customer's ledger | Approval | Production | Yes - Digits approves the app first (see [Getting approved to connect other organisations](#getting-approved-to-connect-other-organisations)) |
| A listing in the Digits Connect integrations directory | Publishing / Partner | Production | Yes - approval first, then a partner-publishing request |

Development and Internal need no request from you; Approval and Publishing / Partner are granted only through the two email requests described below.

Copy the **Client ID** and **Client Secret** from the key set you need - you'll paste them into Apideck in step 7. Always take both values from the same set; a Development Client ID paired with a Production secret will not authenticate.

## 7. Vault Connection Setup

Now that you have your Digits app credentials, configure them in Apideck:

1. Go to [Apideck Configuration > Accounting > Digits](https://platform.apideck.com/configuration/accounting/digits)
2. Under **Use your own client credentials**, enter:
   - **Client ID**: Your Digits Client ID from the Keys tab
   - **Client Secret**: Your Digits Client Secret
3. Review that the requested scopes match what you've configured
4. Click **Save settings**

You can test the connection by clicking **Test Vault**, which will verify the credentials are working.

Your users can now securely authorize connections to their Digits accounts.

## 8. Token handling

Nothing to build here - this is context for why a connection behaves the way it does.

When a user authorizes, Digits issues an access token valid for one hour together with a refresh token. Digits rotates the refresh token on every refresh, so each refresh returns a **new** refresh token, and refresh tokens do not expire on a timer. Apideck stores and rotates them for you.

The one event that ends a connection is an uninstall: Digits revokes the refresh token when a user uninstalls your app, and that user has to authorize again to restore the connection.

## Getting approved to connect other organisations

Development and Internal use need no approval, so you can build against your Developer Sandbox and go live with your own entities and firm clients straight away. To let any other Digits customer install your app:

1. Use your **Production** keys in Apideck (step 7).
2. Complete the publishing metadata on your app:
   - **App Install URL** - an `https://` link where users start your install/connect flow
   - **Privacy Policy** - public URL to your policy
   - **Terms of Service** - public URL to your terms
3. Email `developer@digits.com` with the subject `App Approval Request: <Your App Name>`. Include:
   - What your app does
   - Who it is for
   - Evidence that you handle data securely - for example a recent penetration test or a SOC 2 report

   Ask for an expected timeline in the same email.

Once your app is approved, you can optionally request a listing in the Digits Connect integrations directory by emailing `connect@digits.com` with the subject `Partner Publishing Request: <Your App Name>`.

## FAQ and troubleshooting

### Invalid redirect URI error

**Symptom**: OAuth flow fails with redirect URI mismatch error

**Fix**: Ensure the redirect URI in your Digits app configuration exactly matches `https://unify.apideck.com/vault/callback` (no trailing slash, correct protocol).

### Token exchange fails

**Symptom**: Authorization succeeds but token exchange returns an error

**Fix**:
- Verify your Client Secret is correct (regenerate if needed)
- Confirm both values in Apideck come from the same key set in the **Keys** tab - a Development Client ID with a Production secret (or the reverse) will fail
- If you changed your app's scopes after saving the credentials in Apideck, re-copy the Client ID and Secret from the **Keys** tab (see step 6)

### The app cannot be installed into the target organisation

**Symptom**: A user starts the authorization flow but Digits reports that your app is not available for their organisation

**Fix**: Match the keys to the reach you need (see step 6). Development keys reach only your own Developer Sandbox. Production keys reach your own Digits entities and your firm's clients without approval. Installing into any other organisation requires Digits to approve the app first - see [Getting approved to connect other organisations](#getting-approved-to-connect-other-organisations).

### Scopes not granted

**Symptom**: API calls return permission errors after successful authorization

**Fix**: Confirm `ledger:read` is enabled on your Digits app and that the scopes requested in Apideck match the scopes configured there. Update the Apideck connector settings if needed.

### A working connection stops returning data

**Symptom**: A connection that authorized successfully starts failing

**Fix**: Check whether the user has uninstalled your app in Digits - an uninstall revokes the refresh token, and the user has to authorize again. If the app is still installed, contact [Apideck Support](https://help.apideck.com/en/articles/7774658).

## Resources

- [Digits Developer Documentation](https://developer.digits.com/docs/overview)
- [Digits Authentication Guide](https://developer.digits.com/docs/authentication)
- [Digits App Creation Guide](https://developer.digits.com/docs/app-creation)
- [Digits Publishing Apps Guide](https://developer.digits.com/docs/publishing-apps)