---
title: "Security contexts - Rest PKI Core"
description: "Choose which certificates Rest PKI Core trusts: the standard security contexts, creating your own on the dashboard, the subscription's default, and passing securityContextId in API calls."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/security-contexts"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Security contexts - Rest PKI Core

A **security context** tells [Rest PKI Core](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core) which certificates to trust when it validates a signer's certificate: in signatures,
signature sessions, certificate authentication and signature inspection. A certificate is accepted only if its chain ends at a root that the
security context trusts.

Every instance has standard security contexts, such as ICP-Brasil and the Lacuna Test PKI. When none of them fits, for instance because your
users have certificates issued by a private CA, create a security context of your own on the dashboard.

## Standard security contexts

Rest PKI Core creates these security contexts on every instance, with the same IDs everywhere. They are visible to every subscription and
can't be changed:

| Security context | ID | Trusts |
| --- | --- | --- |
| `PkiBrazil` | `201856ce-273c-4058-a872-8937bd547d36` | ICP-Brasil |
| `PkiBrazilExtended` | `3ce63ec8-2c71-4181-b4cd-33c3ba6d614f` | Official Brazilian state entities: ICP-Brasil and gov.br |
| `GovBR` | `5d323217-c031-4eed-9001-1cd82d86a8b5` | gov.br |
| `PkiBrazilWithENotariado` | `f963e2dd-1606-4937-b903-01926785dcf0` | ICP-Brasil and the e-Notariado hierarchy (Colégio Notarial do Brasil) |
| `PkiBrazilWithGovBrAndENotariado` | `4bf4409f-db45-4aab-91bf-2c73930ca556` | ICP-Brasil, gov.br and the e-Notariado hierarchy |
| `PkiItaly` | `c438b17e-4862-446b-86ad-6f85734f0bfe` | The trusted CAs of the Italian PKI |
| `WindowsServer` | `3881384c-a54d-45c5-bbe9-976b674f5ec7` | The root certificates that Microsoft deems trustworthy |
| `LacunaTest` | `803517ad-3bbc-4169-b085-60053a8f6dbf` | ICP-Brasil, the root certificates that Microsoft deems trustworthy and the Lacuna Test PKI. For development only (see [Test certificates](https://docs.lacunasoftware.com/en-us/articles/pki-guide/test-certs#rest-pki-core)) |

In .NET, the class `StandardSecurityContexts` (namespace `Lacuna.RestPki.Api`) has all of them, such as `StandardSecurityContexts.PkiBrazil`; in
Java, the class `SecurityContext` has all but the two e-Notariado ones, such as `SecurityContext.pkiBrazil`. The four that
[Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki) also has, `PkiBrazil`, `PkiItaly`, `WindowsServer` and `LacunaTest`, have the same IDs there.

## Choosing the security context of a call

Pass the ID of the security context in the `securityContextId` field of the request. These APIs take it:

| API | Route |
| --- | --- |
| [Signature sessions](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-sessions) | `POST api/signature-sessions` |
| [Two-step signatures](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/two-step-signatures) | `POST api/signature` |
| [Certificate authentication](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/cert-auth) | `POST api/v2/authentication` |
| [Signature inspection](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection) | `PUT api/signature-inspection` |
| Archival extension of a signature | `POST api/signature/archival-extension` |
| The Rest PKI APIs that Rest PKI Core serves | Starting a signature (`Api/PadesSignatures`, `Api/CadesSignatures`, `Api/XmlSignatures/...`), the `Open` routes and `Api/Authentications` |

On .NET, for instance:

```cs
var response = await restPkiService.CreateSignatureSessionAsync(new CreateSignatureSessionRequest() {
	ReturnUrl = "https://localhost:5001/signature-callback",
	SecurityContextId = StandardSecurityContexts.PkiBrazil,
});
```

When a call gives no `securityContextId`, Rest PKI Core uses the subscription's [default security context](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/security-contexts#default) or, if the subscription has
none, the instance's default, which is `PkiBrazil` unless the instance was configured otherwise. The Rest PKI signature routes are an exception:
without a security context, they trust what the signature policy defines, and fail with `SecurityContextRequired` when the policy defines nothing,
as `StandardPadesSignaturePolicies.Basic` does. The Rest PKI certificate authentication route, `Api/Authentications`, always needs the ID.

> **Tip**
>
> Name the security context in every call instead of relying on a default. Your code then trusts the same certificates whichever subscription or
> instance it runs against.

## Managing security contexts on the dashboard

Security contexts are managed on the dashboard of the instance, by users with the **Manager** or **Admin** role (see
[Choosing roles](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#roles)). On the left menu, click **Security contexts**. The list shows the standard security contexts and those
of the subscription, with their **Type**: `Standard` for the standard ones, `Custom` for those created in the subscription and `System` for those
created in the instance's system administration area, which every subscription can use.

### Creating a security context

1. On **Security contexts**, click **Add**. If the dashboard is showing all subscriptions, select a subscription first: the security context
   belongs to the subscription it is created in.
1. Fill in a **Name**, unique in the subscription (up to 100 characters).
1. Under **Trusted roots**, upload the root certificates of the CAs to trust. Each one must be a root certificate, that is, self-signed.
1. Under **Additional standard trust arbitrators**, check the standard sets of roots to trust as well: **PKI Brazil**, **Gov.BR**,
   **Brazilian state entities (includes PKI Brazil and gov.br)**, **PKI Italy**, **Windows Server**, **Lacuna Test** and **e-Notariado**.
1. Optionally, choose a **Timestamp tier** and check the option under **Other options** (see [Settings](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/security-contexts#settings) below).
1. Click **Save**.

The new security context gets an ID, shown as **Id** when you open it from the list: use it as the `securityContextId` of your calls.

A security context trusts the union of its trusted roots and of the standard trust arbitrators you checked. A security context that trusts
nothing can be saved, but every call that uses it fails.

If the dashboard can't save the security context, it tells you why:

| Message | What to do |
| --- | --- |
| There is already a security context with the same given name | Choose another **Name** |
| The certificate of one or more trusted roots being added is invalid | Check that the file you uploaded is a certificate |
| One or more of the given trusted roots are not root certificates | Upload the root of the chain, not an intermediate CA or end-user certificate |
| One or more of the trusted roots being added already exists on the security context | When editing, don't upload a root the security context already has |

### Settings of a security context

| Setting | Effect |
| --- | --- |
| **Timestamp tier** | The [timestamp tier](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/requesting-timestamps) used when a signature policy needs a timestamp. With **None**, Rest PKI Core picks the tier from the trusted roots (the ICP-Brasil or Lacuna Test tier) or else the default tier, and the signature fails with `SecurityContextNotConfiguredForTimestamping` when there is none |
| **Ignore "revocation status unknown" validation failures** | Accepts certificates whose revocation status can't be determined, in signatures, signature sessions and the Rest PKI signature and `Open` routes. Certificate authentication and signature inspection don't use it: they take their own `ignoreRevocationStatusUnknown` parameter, and certificate authentication, when the parameter is omitted, follows **Ignore unknown revocation status by default** in **Settings** > **General settings** |

### Editing and deleting

Click the name of a security context of the subscription to change it, then **Save**, or to **Delete** it. The standard security contexts open
read-only.

> **Warning**
>
> Rest PKI Core doesn't check whether a security context is in use before deleting it. After the deletion, calls that name it fail with
> `SecurityContextNotFound`, and signature sessions, two-step signatures and certificate authentications started with it fail when they complete. If
> it was the subscription's default, calls that name no security context fail too. Before deleting, make sure no application uses it, and choose another
> default if needed.

## The default security context

To choose the security context used by calls that name none, go to **Settings** > **General settings** > **Default security context** on the
dashboard. This needs the **Manager** or **Admin** role. Without a default, Rest PKI Core uses the instance's.

## Through the API

The dashboard manages security contexts through `api/security-contexts`, which is not part of the [API reference](https://core.pki.rest/swagger),
and the client libraries have no methods for it. An application whose key has the **Worker** role, as most integrations do, can use any security
context by its ID, but can't list, create or change them.

## Moving from Rest PKI

The standard security contexts that Rest PKI has keep their IDs on Rest PKI Core, so code that names them works unchanged. A security context you
created on Rest PKI is not carried over: [create it again](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/security-contexts#create) on Rest PKI Core and use its new ID. See
[Moving from Rest PKI](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/migrating-from-rest-pki#security-contexts).

## See also

* [Choosing roles](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/get-started#roles)
* [Test certificates](https://docs.lacunasoftware.com/en-us/articles/pki-guide/test-certs#rest-pki-core)
* [Signature inspection](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/signature-inspection)