PEG REST API on Privacera Self-Managed Deployment¶

For the Privacera Self-Managed deployment, the PEG API endpoints are available at:

1

https://<privacera_hostname>/api/peg/v2/

Please check with your installation team for the value of <privacera_hostname> and confirm if any custom configuration has been applied.

API Endpoints¶

The PEG REST API includes the following endpoints:

Authentication¶

The PEG API uses JWT tokens for authentication. For detailed instructions on generating and using JWT tokens, see JWT Tokens for Encryption.

When making API requests, include the JWT token in the Authorization header:

1

-H "Authorization: Bearer <JWT_TOKEN>"

API Request Parameters¶

Common Parameters¶

API Examples¶

1. Single Data Protection (/api/peg/v2/protect)¶

Request:

1
2
3
4
5
6
7
8

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "scheme": "SYSTEM_EMAIL",
    "data": "user@example.com"
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/protect'

Response:

1
2
3
4

{
    "data": "8nDs@pQxYZ.kVw",
    "responseStatus": "SUCCESS"
}

2. Single Data Unprotection (/api/peg/v2/unprotect)¶

Request:

1
2
3
4
5
6
7
8
9

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "scheme": "SYSTEM_EMAIL",
    "data": "8nDs@pQxYZ.kVw",
    "presentationScheme": "EMAIL_MASK_DOMAIN"
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/unprotect'

Response:

1
2
3
4

{
    "data": "user@*****.***",
    "responseStatus": "SUCCESS"
}

3. Single Data Masking (/api/peg/v2/mask)¶

Request:

1
2
3
4
5
6
7
8

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "scheme": "MASK_SSN",
    "data": "123-45-6789"
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/mask'

Response:

1
2
3
4

{
    "data": "XXX-XX-6789",
    "responseStatus": "SUCCESS"
}

4. Multi-Data Protection (/api/peg/v2/multi/protect)¶

Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "schemes": ["SYSTEM_EMAIL", "SYSTEM_SSN", "SYSTEM_CREDITCARD"],
    "datas": [
        ["user1@example.com", "user2@example.com"],
        ["123-45-6789", "987-65-4321"],
        ["4111-1111-1111-1111", "5555-5555-5555-4444"]
    ]
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/multi/protect'

Response:

1
2
3
4
5
6
7
8

{
    "datas": [
        ["a1b2@cDe3.fGh", "j4k5@lMn6.oPq"],
        ["XXX-XX-6789", "XXX-XX-4321"],
        ["XXXX-XXXX-XXXX-1111", "XXXX-XXXX-XXXX-4444"]
    ],
    "responseStatus": "SUCCESS"
}

5. Multi-Data Unprotection (/api/peg/v2/multi/unprotect)¶

Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "schemes": ["SYSTEM_EMAIL", "SYSTEM_SSN"],
    "datas": [
        ["a1b2@cDe3.fGh", "j4k5@lMn6.oPq"],
        ["XXX-XX-6789", "XXX-XX-4321"]
    ],
    "presentationSchemes": ["EMAIL_MASK_DOMAIN", null]
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/multi/unprotect'

Response:

1
2
3
4
5
6
7

{
    "datas": [
        ["user1@*****.***", "user2@*****.***"],
        ["123-45-6789", "987-65-4321"]
    ],
    "responseStatus": "SUCCESS"
}

6. Multi-Data Masking (/api/peg/v2/multi/mask)¶

Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "schemes": ["MASK_EMAIL", "MASK_SSN", "MASK_CREDITCARD"],
    "datas": [
        ["user1@example.com", "user2@example.com"],
        ["123-45-6789", "987-65-4321"],
        ["4111-1111-1111-1111", "5555-5555-5555-4444"]
    ]
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/multi/mask'

Response:

1
2
3
4
5
6
7
8

{
    "datas": [
        ["user*@*******.***", "user*@*******.***"],
        ["XXX-XX-6789", "XXX-XX-4321"],
        ["XXXX-XXXX-XXXX-1111", "XXXX-XXXX-XXXX-4444"]
    ],
    "responseStatus": "SUCCESS"
}

7. Get Available Schemes (/api/public/crypto/schemes/byuser)¶

Request:

1
2
3

curl -X GET \
-H "Authorization: Bearer <JWT_TOKEN>" \
'https://<PRIVACERA_HOST>/api/public/crypto/schemes/byuser'

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
    "schemes": [
        {
            "name": "SYSTEM_EMAIL",
            "description": "Standard email encryption scheme",
            "algorithm": "FPE",
            "format": "EMAIL",
            "scope": "ALL",
            "systemDefined": true,
            "permissions": ["ENCRYPT", "DECRYPT"]
        },
        {
            "name": "SYSTEM_SSN",
            "description": "Social Security Number encryption",
            "algorithm": "FPE",
            "format": "SSN",
            "scope": "ALL",
            "systemDefined": true,
            "permissions": ["ENCRYPT", "DECRYPT"]
        }
    ],
    "responseStatus": "SUCCESS"
}

User Impersonation¶

The PEG API supports user impersonation, allowing authorized users to perform encryption operations on behalf of other users.

Requirements for Impersonation¶

For a user to impersonate another user, the following conditions must be met:

1. The authenticated user (the user whose JWT token is used) must have the Impersonate permission for the relevant scheme in the scheme policy
2. The impersonated user (specified in the user parameter) must exist in the system
3. The impersonated user must have access to the relevant encryption scheme via a scheme policy

Using Impersonation¶

To impersonate another user, include the user parameter in your API request:

1
2
3
4
5
6
7
8
9

curl -X POST \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "scheme": "SYSTEM_EMAIL", 
    "data": "user@example.com",
    "user": "user_being_impersonated"
}' \
'https://<PRIVACERA_HOST>/api/peg/v2/protect'

In this example: - The authentication and authorization is performed using the JWT token of the calling user - The operation is recorded in audit logs as performed by user_being_impersonated - Any scheme policy checks are performed against the user_being_impersonated user's permissions

Common Use Cases¶

User impersonation is particularly useful for:

• Service applications that need to perform encryption/decryption operations on behalf of multiple end users
• Administrative tools that manage data for various users in the system
• Batch processing systems that handle operations for different user accounts

Related Terminology¶

As described in the Terminology and Roles documentation:

• Authentication User: The user who has access to the PEG service and can impersonate other users (must have the Impersonate permission)
• Impersonated User: The user on whose behalf the operation is performed (must exist in the system and have appropriate scheme permissions)

Error Handling¶

Common Error Codes¶

Partial Success in Bulk Operations¶

For bulk operations, if an error occurs with one element, the API will still process other elements and return a "Partial Success" status.

Example response with partial success:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
    "datas": [
        ["a1b2@cDe3.fGh", null],
        ["XXX-XX-6789", "XXX-XX-4321"]
    ],
    "errors": [
        [null, {"message": "Invalid data format for email"}],
        [null, null]
    ],
    "responseStatus": "PARTIAL_SUCCESS"
}

Related Resources¶

• JWT Tokens for Encryption
• Encryption Schemes
• Presentation Schemes
• Masking Schemes

Comments