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

# Branding

> How your organisation and your credentials appear in the holder's wallet.

Two separate things are branded, at two different levels. They are easy to confuse, and setting one expecting the other is the most common mistake.

|                     | Issuer branding                                     | Credential card branding                      |
| ------------------- | --------------------------------------------------- | --------------------------------------------- |
| What it controls    | Who issued this — your organisation's name and logo | How one credential's card looks               |
| Scope               | Your whole tenant, every credential you issue       | One preset or template                        |
| Set on              | Your project, at provisioning time                  | `branding` on a credential preset or template |
| Change it yourself? | No — [ask us](#changing-your-issuer-branding)       | No — it is fixed at creation                  |

## Issuer branding

Your issuer display is the identity holders see attached to every credential you issue: a **display name** and an optional **logo**. It is read by the didx:me wallet and by third-party wallets, which fetch it from your published issuer metadata.

| Field         | Constraint                                                                         |
| ------------- | ---------------------------------------------------------------------------------- |
| `displayName` | Required. Non-empty after trimming. The organisation name holders would recognise. |
| `logoUrl`     | Optional. Must be an `https` URL, publicly fetchable.                              |
| `logoAltText` | Optional. Alt text for the logo. Keep it under 50 characters.                      |

<Note>
  `logoUrl` is restricted to `https` because the platform fetches it server-side to publish your issuer metadata. Plain
  `http`, `localhost` and other schemes are rejected at the boundary.
</Note>

<Warning>
  `displayName` is required when your tenant is provisioned, and for good reason: without it the platform falls back to
  the internal project name, so you would issue as something like `acme-me-creds`. Third-party wallets read that from
  your metadata, and credentials already in holders' wallets keep showing whatever name was current when they were
  issued.
</Warning>

### Changing your issuer branding

There is currently no self-service endpoint for this — issuer branding is applied during tenant provisioning and changed by DIDx on request.

To change your display name, logo, or alt text, ask in the [DIDx Slack](https://join.slack.com/t/didx-xyz/shared_invite/zt-3wixgicbk-oLCOAjpk7HDEwv5avRFbyA) with:

* your tenant alias,
* the new `displayName`, and/or
* a public `https` URL for the new logo, plus its alt text.

The change applies to your issuer metadata going forward. Credentials already issued keep the branding they were issued with until the holder's wallet refreshes them.

<Tip>
  A self-service endpoint for issuer branding is on the roadmap. Until it ships, treat your display name as something
  you set once, carefully, at onboarding.
</Tip>

## Credential card branding

Each credential preset or template can carry a `branding` block that controls how that credential's card renders in the wallet.

| Field                | Type   | Description                                         |
| -------------------- | ------ | --------------------------------------------------- |
| `backgroundColor`    | string | Card background, as a 6-digit hex code (`#RRGGBB`)  |
| `textColor`          | string | Card text colour, as a 6-digit hex code (`#RRGGBB`) |
| `backgroundImageUrl` | string | URL of a background image for the card              |

All three are optional. Omit the block entirely and the wallet falls back to its default card styling.

```bash theme={null}
curl -X POST "$BASE_URL/me-creds/api/v1/presets/credentials/sd-jwt" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialFormat": "sd-jwt",
    "code": "membership",
    "templateName": "Membership Card",
    "templateDescription": "Proof of active membership",
    "templateAttributes": {
      "memberNumber": {
        "type": "string",
        "name": "Member Number",
        "required": true,
        "alwaysDisclosed": false
      }
    },
    "branding": {
      "backgroundColor": "#0066CC",
      "textColor": "#FFFFFF",
      "backgroundImageUrl": "https://cdn.example.com/acme/card-bg.png"
    }
  }'
```

The same `branding` block is accepted on credential templates, for the [custom template path](/products/didx-me/guides/issuers/create-credential-template).

### Colours must be 6-digit hex

`backgroundColor` and `textColor` accept `#RRGGBB` and nothing else. Named colours (`red`), functional forms (`rgb(0,102,204)`), and 3- or 8-digit hex are all rejected with a 400.

This is deliberate rather than an oversight: the wallet derives tinted accents from your colours by appending an alpha byte to the value, which only produces a valid colour when the input is exactly six hex digits.

### Branding is fixed at creation

There is no update endpoint for credential presets or credential templates, so the `branding` you supply at creation is the branding that credential keeps.

* **Presets** are immutable and cannot be deleted. To change a preset's branding, publish a new preset (for example `acme:membership-v2`) and issue against that instead.
* **Templates you created yourself** can be deleted and recreated, so long as you are willing to lose the template id.
* **Preset-managed templates cannot be deleted.** The template the platform materialized from a preset refuses deletion with a 400 — `Template '<id>' is managed by a preset and cannot be deleted.` Publish a new preset instead.

Either way, credentials already issued keep the branding they were issued with. Get the colours right before you issue at volume.

## What the holder sees

Both layers arrive together in the wallet. For each credential a holder opens, the wallet renders:

| From                    | Shown as                                                 |
| ----------------------- | -------------------------------------------------------- |
| Issuer `displayName`    | Who issued the credential                                |
| Issuer `logoUrl`        | The issuer's logo on the credential detail view          |
| `templateName`          | The credential's title                                   |
| `templateDescription`   | Supporting text under the title                          |
| `branding.*`            | The card's background, text colour, and background image |
| Attribute `name` labels | The row labels in the claims list                        |

So a well-branded credential needs both: your organisation set up correctly at onboarding, and a `branding` block on the preset.