This page is for admins who make Buttons. The last part is also for the developers of the target page.

A Link button opens a URL in the browser. The target page cannot tell from the URL alone that the click came from
OneClick. The **Signed link** section solves this. On each click, OneClick makes a new signed token and adds it to
the URL as a query parameter. The target page verifies the token with a secret that only OneClick and the target
page know.

A Link button without a Signed link opens the URL as it is.

## How a signed click works

1. A Pipedrive user clicks the Link button.
2. The browser opens an empty window.
3. OneClick checks the user and makes a token on the OneClick server. The token is signed with the secret.
4. OneClick adds the token to the URL in the query parameter, for example `?oneclick_token=<token>`.
5. The window opens the URL.
6. The target page verifies the token and then shows its content.

If OneClick cannot make the token, it closes the window and the Panel shows an error. OneClick never opens the URL
without the token. If the browser blocks the window, the error tells the user to allow pop-up windows for OneClick.

## Add a Signed link

1. Open the Link button in the Button editor.
2. Click **Signed link** in the menu. The section shows **No Signed link added yet**.
3. Click **Add a Signed link**. OneClick makes a new secret and fills in the default values.
4. Change **Query parameter name** and **Token lifetime (seconds)** if necessary.
5. Copy the secret from **Signing secret** and give it to the developer of the target page.
6. Click **Save**.

## The settings

![The Signed link section of the Link button Open signed report, with Query parameter name, Token lifetime (seconds), the hidden Signing secret and the buttons Reveal, Generate a new secret and Remove the Signed link](https://res.cloudinary.com/zimple/image/upload/f_auto,q_auto/oneclick-docs/buttons/link-button/sections/signed-link/signed-link-section.png)

| Setting                      | Default          | Rules                                                                       |
| ---------------------------- | ---------------- | --------------------------------------------------------------------------- |
| **Query parameter name**     | `oneclick_token` | Starts with a letter. Letters, digits, hyphens and underscores. 64 characters or less. |
| **Token lifetime (seconds)** | 60               | From 15 to 300 seconds.                                                     |
| **Signing secret**           | A new random key | A 256-bit key in Base64URL text. Passwords are not accepted.                |

If the URL already has a query parameter with the same name, OneClick replaces it with the token.

### The signing secret

Use the key that OneClick makes, or paste a 256-bit Base64URL key of your own. A key of 32 bytes is 43 characters
long, or 44 characters with the `=` padding at the end.

OneClick encrypts the secret and never sends it to the browser of a user. When you open the saved Button again, the
field hides the secret:

- The admin who made the secret can click **Reveal** to show it again.
- For other admins, the secret stays hidden. They can still replace it or remove the Signed link.

**Generate a new secret** replaces the secret at once. Tokens with the old secret then fail. Give the new secret to
the target page at the same time.

**Remove the Signed link** removes the setting. The Link button then opens the URL without a token.

### Copies and transfers

- A copy of the Button in the same Pipedrive company keeps the secret.
- A [Button transfer](/docs/buttons/transfer-a-button) to another Pipedrive company keeps the query parameter name and
  the token lifetime, but not the secret. The section then says that the Button carries no signing secret. Until an
  admin of that company generates a new secret, the Button opens the URL without a token.

## Verify the token on the target page

The token is a [JSON Web Token](https://datatracker.ietf.org/doc/html/rfc7519) (JWT) with the algorithm `HS256`. To
verify it, the target page does these steps:

1. Read the token from the query parameter.
2. Decode the Base64URL secret into its 32 bytes. Use these bytes as the HMAC key, not the text of the secret.
3. Verify the `HS256` signature with the key. Accept only the algorithm `HS256`.
4. Make sure that the time in `exp` is not in the past.
5. Use the claims, for example to find the Pipedrive user.

The token has these claims:

| Claim           | Type    | Value                                                          |
| --------------- | ------- | -------------------------------------------------------------- |
| `company_id`    | number  | The ID of the Pipedrive company.                               |
| `user_id`       | number  | The ID of the Pipedrive user who clicked the Button.           |
| `is_user_admin` | boolean | `true` if the user is a Pipedrive admin.                       |
| `iat`           | number  | The time when OneClick made the token, in seconds since 1970.  |
| `exp`           | number  | The time when the token expires, in seconds since 1970.        |

The token does not contain the deal, the person or the organization. The URL can contain them, but they are not
signed. Do not trust them for access control.

OneClick makes a new token for each click, but it does not prevent a second use of a token. If the target page must
accept a token only one time, it must keep a list of the used tokens until they expire.

The `is_user_admin` value is never more than five minutes old: OneClick checks the admin status with Pipedrive again
when the stored status is older.

For an example in Node.js, see [Verify a Signed link](/docs/using-oneclick-with/nodejs/verify-a-signed-link).