---
sourceDocument: Brazil API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/api-reference

 Release :

    - brazil

ft:locale :

    - en-US

ft:publication_title :

    - Brazil API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# SecretsAPI - Scoped

# SecretsAPI - Scoped {#ariaid-title1}

Release version: Brazil  
Updated October 4, 2026  
![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read  
The SecretsAPI provides an entry point for delivering credentials to a MID Server without requiring the caller to know the underlying storage mechanism. This scoped API enforces a comprehensive authorization
chain before decrypting and returning secret values.
The primary consumer of this API is MID Server credential delivery. The API allows MID Server callers to set a caller-identity property on the session before calling getSecret() or getSecrets(). This enables alias groups configured with `filter_mode="mid_scoped"` to restrict which credentials a given MID agent is allowed to see. This API is intended for use by internal platform scripts and MID Server credential delivery.

Every call to getSecret() or getSecrets() passes through a seven-step authorization chain (banned table, lockdown, type compatibility, table
ACL, row ACL, consumer grant, MAP policy) before any secret value is decrypted. Denial at any step exits immediately with no secret material touched. All denials return a uniform error to the caller. The specific reason is recorded
only in the audit log (enable with` glide.usg.audit.trace=true`) and is never exposed to callers.  
The API returns one of two shapes:

* A plain decrypted value (Password2 field --- for example, a credential's password).
* A full credential record (`value_field="*"` groups --- every field of a credential, each decrypted).
{#SecretsAPI__ul_uwn_pwh_5kc}

## Access instructions and requirements {#SecretsAPI__section_g1t_jwh_5kc}

The SecretsAPI is supported by the [Unified Secrets Gateway](https://www.servicenow.com/docs/access?context=usg-landing&version=brazil&pubname=brazil-platform-security&ft:locale=en-US) (USG) product and is available with the USG plugin (com.glide.usg.global) and requires the com.glide.kmf.global plugin. The API is provided within the sn_usg_ns namespace.

To access this API, use `var api = new sn_usg_ns.SecretsAPI();` with no constructor arguments.

The sn_kmf.cryptographic_manager role is required to configure sys_secret_alias_group and sys_secret_alias_consumer records.

## SecretsAPI - getSecret(String alias) {#ariaid-title2}

Retrieves a single secret by alias, resolving the alias into a table/field/record coordinate and running the authorization chain before decrypting and returning the value.
This method identifies the calling context (including the MID agent identity if set), then runs the
authorization chain (table ACL, row ACL, consumer grant if applicable) before decrypting and returning the value. Returns a JSON string that must be parsed by the caller.
{#SecretsAPI-getSecret_S__table_getsecret_params__entry__3}

| Name | Type | Description |
|-|-|-|
| alias | String | Required. The secret alias to resolve. Must not be empty. Valid formats: * Direct: `"<table>.<field>.<sys_id>"`. For example `"discovery_credentials.password.<sys_id>"`. * Group: `"<groupName>.<alias>"`. For example` "mid_creds.host1"`. Default value (or behavior if not provided): throws rather than returning nothing. |
[Table 1. Parameters]

{#SecretsAPI-getSecret_S__table_getsecret_params} {#SecretsAPI-getSecret_S__table_getsecret_returns__entry__2}

| Type | Description |
|-|-|
| Object | JSON string (must be parsed by caller) containing one of two shapes: * For a Password2 field: {"alias": "String", "value": "String"} * For a full credential (value_field="\*" alias groups): {"alias": "String", "fields": {"<fieldName>": "String", ...}} On failure, the scripted wrapper returns null rather than throwing. Every failure mode (bad alias, access denied, record not found) collapses to the same null. This is intended behavior to prevent probing for configuration or secrets. |
[Table 2. Returns]

{#SecretsAPI-getSecret_S__table_getsecret_returns}  
This example shows two variants: retrieving a plain secret (Password2 field) and retrieving a full credential record.

    var api = new sn_usg_ns.SecretsAPI();

    // Variant A --- plain Secret (alias group's value_field is a specific field, e.g. "password")
    var rawA = api.getSecret('discovery_credentials.password.' + credentialSysId);
    if (rawA) {
        var secretResult = JSON.parse(rawA);
        gs.info('Fetched credential for alias: ' + secretResult.alias);
        // secretResult.value --- the decrypted password
    }

    // Variant B --- Credential, full record (alias group's value_field is "*") --- per KB0562777
    var rawB = new sn_usg_ns.SecretsAPI().getSecret('mid_creds.host1');
    if (rawB) {
        var credentialResult = JSON.parse(rawB);
        var password = credentialResult.fields['password'];
        // credentialResult.fields --- every decrypted field on the credential record
    }

Output:

    Fetched credential for alias: discovery_credentials.password.3f412b8a...

## SecretsAPI - getSecrets(String groupName) {#ariaid-title3}

Retrieves every secret belonging to a named alias group in one call, returning a pre-partitioned result
with successes and per-alias failures so the caller does not have to loop and catch individually.
This is the bulk MID-credential-delivery shape. A MID agent can fetch every credential it is scoped to from one mid_scoped group in a single round trip. The method returns a JSON string that must be parsed by the caller.
{#SecretsAPI-getSecrets_S__table_getsecrets_params__entry__3}

| Name | Type | Description |
|-|-|-|
| groupName | String | Required. The alias group to fetch. Must not be empty. Valid values: any existing Alias Group Name. For example a MID-scoped credential group such as `"mid_credentials"`. Table: Secret Alias Group \[sys_secret_alias_group\], Field: Alias Group Name Default value or behavior if not provided: throws rather than defaulting to any group. |
[Table 3. Parameters]

{#SecretsAPI-getSecrets_S__table_getsecrets_params} {#SecretsAPI-getSecrets_S__table_getsecrets_returns__entry__2}

| Type | Description |
|-|-|
| Object | JSON string (must be parsed by caller) containing a successful array or two distinct failure levels. Data type: Object {"successful": [<secret objects, same shapes as getSecret's return>], "failed": [{"alias": "String", "error": "String"}, ...]} Possible values: * Success: The `"successful"` array contains entries matching getSecret's Password2 or Credential shapes. * Failure: The `"failed"` array contains entries for aliases that could not be fetched, identifying the alias and the reason (for example, ACCESS_DENIED, RECORD_NOT_FOUND). A failure array contains two distinct levels: * Group-level failure: If the named group does not exist, the entire call fails and the scripted wrapper returns null, exactly like getSecret()'s failure case. Nothing is returned, not even a failed array. * Per-alias failure: If the group exists but one or more members can't be fetched, the call still succeeds and returns a normal object. The failing aliases appear in the failed array instead of successful. A caller receives a usable response in this case and must check the failed array explicitly, since a non-null result does not indicate that every member succeeded. {#SecretsAPI-getSecrets_S__ul_tyt_kc4_5kc} {#SecretsAPI-getSecrets_S__ul_wh1_tb4_5kc} |
[Table 4. Returns]

{#SecretsAPI-getSecrets_S__table_getsecrets_returns}  
This example shows batch retrieval of credentials from a named alias group. The result is checked for successful entries.

    var json = new sn_usg_ns.SecretsAPI().getSecrets('mid_credentials');
    var result = JSON.parse(json);
    result.successful.forEach(function(secret) {
        gs.log('Alias: ' + secret.alias);
    });

Output:

    Alias: mid_credentials.3f412b8a...

### Troubleshooting {#SecretsAPI-getSecrets_S__section_ckx_rc4_5kc}

{#SecretsAPI-getSecrets_S__table_qx1_sc4_5kc__entry__2}

| Error | Likely cause / fix |
|-|-|
| ACCESS_DENIED with no context | Enable `glide.usg.audit.trace=true` (reloads live, no restart) to see the denying gate in the audit log. Never exposed to the caller directly. Common causes: * Missing Row ACL, * Missing Consumer Grant (external/MID callers), * MAP Policy denial, * The alias group is in a LOCKDOWN state. {#SecretsAPI-getSecrets_S__ul_exg_xc4_5kc} |
| RECORD_NOT_FOUND | The alias_field value doesn't exist in the target table, or for `filter_mode=mid_scoped`, the record doesn't have `applies_to="all"` or the calling MID Server's ID in `mid_list`. |
| INVALID_FORMAT | Alias string doesn't match either addressing mode: * Tier 3 `"table.field.sys_id"` * Tier 2 `"group_name.alias"` {#SecretsAPI-getSecrets_S__ul_v1r_1d4_5kc} |
[ ]

{#SecretsAPI-getSecrets_S__table_qx1_sc4_5kc}