> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build & publish

> Register your app in the Developer console, configure its marketplace listing, submit it for review, and follow security best practices.

This page covers registering your app, configuring its listing, and getting it published to
the Salesive Apps marketplace.

## Register your app

<Steps>
  <Step title="Open the Developer console">
    In your Salesive store dashboard, go to **Apps → Developer** and choose **Create app**.
  </Step>

  <Step title="Fill in the basics">
    Give your app a name, tagline, description, icon, and category. Add at least one
    **redirect URI** (the callback URL your server handles after consent) and select the
    **scopes** your app needs.
  </Step>

  <Step title="Save your credentials">
    On creation you receive a `client_id` and a `client_secret`. **The secret is shown only
    once** — store it securely. You can regenerate it later if needed.
  </Step>

  <Step title="Set your install URL">
    Set the **Install / launch URL** to where merchants begin installing — the page on your
    site that kicks off the [OAuth flow](/apps/oauth-install). This is what the marketplace
    "Install" button opens.
  </Step>

  <Step title="Add a webhook URL (optional)">
    Set a **Webhook URL** to receive real-time, signed events when store data your app can
    access changes — no polling. The console also shows your **signing secret** for verifying
    deliveries. See [Webhooks](/apps-api/webhooks).
  </Step>
</Steps>

<Warning>
  Treat the `client_secret` like a password. Store it only on your server, never in client-side
  code, a mobile app, or a public repository. If it leaks, regenerate it from the Developer
  console.
</Warning>

### Registering via the API

You can also manage apps programmatically (authenticated with your Salesive dashboard session).
Creating an app returns the secret once:

```bash theme={null}
curl -X POST https://api.salesive.com/api/v1/apps/developer \
  -H "Authorization: Bearer <your-dashboard-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fulfillment Buddy",
    "tagline": "Auto-sync shipments to your 3PL",
    "redirectUris": ["https://yourapp.com/oauth/callback"],
    "category": "fulfillment",
    "appUrl": "https://yourapp.com/install",
    "scopes": ["READ_ORDERS", "WRITE_SHIPPING"]
  }'
```

| Endpoint                                     | Purpose                                       |
| -------------------------------------------- | --------------------------------------------- |
| `POST /apps/developer`                       | Create an app (returns `client_secret` once). |
| `GET /apps/developer`                        | List your apps.                               |
| `GET /apps/developer/:id`                    | Get one of your apps.                         |
| `PUT /apps/developer/:id`                    | Update listing, redirect URIs, or scopes.     |
| `POST /apps/developer/:id/regenerate-secret` | Rotate the client secret.                     |
| `POST /apps/developer/:id/submit`            | Submit the app for review.                    |
| `DELETE /apps/developer/:id`                 | Delete the app.                               |

## Test your app before submitting

While your app is a **draft**, you can install it on your own store to test the full OAuth
flow end to end. Run through [the install flow](/apps/oauth-install), confirm your token
exchange works, and verify your API calls succeed with the scopes you requested.

## Submit for review

When your app is ready, submit it for review from the Developer console (or
`POST /apps/developer/:id/submit`). Your app moves through this lifecycle:

<Steps>
  <Step title="Draft">
    Visible only to you. Editable and installable on your own store for testing.
  </Step>

  <Step title="Pending">
    Submitted and awaiting review by the Salesive team.
  </Step>

  <Step title="Approved">
    Published and discoverable in the Apps marketplace. Merchants can install it.
  </Step>

  <Step title="Rejected">
    Sent back with reviewer feedback. Address the feedback and resubmit.
  </Step>
</Steps>

<Note>
  Before submitting, declare at least one scope and make sure your listing (name, description,
  icon, install URL) is complete. Apps are only listed publicly once approved.
</Note>

## How merchants install your app

Once approved, your app appears in the **Apps** marketplace inside every merchant's dashboard.
A merchant opens your listing and clicks **Install**, which launches your install URL and runs
the [OAuth consent flow](/apps/oauth-install). You can also share a direct install link to
your listing or install URL from your own marketing site.

Installed apps appear under **Apps → Installed apps**, where merchants can review the granted
permissions and uninstall at any time.

## Security best practices

<CardGroup cols={2}>
  <Card title="Keep the secret server-side" icon="lock">
    Never ship the `client_secret` in client code. Complete the token exchange only from your
    backend.
  </Card>

  <Card title="Always use PKCE" icon="shield-halved">
    Generate a fresh `code_verifier` per install and verify `state` on the callback to prevent
    CSRF.
  </Card>

  <Card title="Request least privilege" icon="key">
    Ask only for the scopes you use. Fewer permissions means higher merchant trust and approval.
  </Card>

  <Card title="Use exact redirect URIs" icon="link">
    Register full, exact callback URLs. Salesive rejects redirects that don't match.
  </Card>

  <Card title="Rotate refresh tokens" icon="rotate">
    Refresh tokens rotate on use — persist the newest one and discard the old.
  </Card>

  <Card title="Handle uninstalls" icon="trash">
    Treat a `401` "no longer installed" as an uninstall: stop calling the API and purge stored
    tokens for that store.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Review the install flow" icon="arrow-right-to-bracket" href="/apps/oauth-install">
    The full OAuth 2.1 + PKCE handshake.
  </Card>

  <Card title="Browse scopes" icon="key" href="/apps/scopes-permissions">
    Pick the right permissions for your app.
  </Card>
</CardGroup>