Using service accounts

A Secure Web Sessions service account enables you to use the SWS API to authenticate to SWS and access data.

When you create a service account, a new public/private key pair is generated and downloaded to your machine. This is the only copy of the private key. You are responsible for storing the private key securely. Note its location and ensure the key is accessible to your application; it needs the key to make authenticated API calls.

Before you begin

You need to be a SWS Admin to create a service account.

Create a service account

  1. In the Secure Web Sessions portal, go to Identities > Service accounts.

  2. Click the Create service account button.

  3. Set the following properties:



    Name The name of the service account. This name appears in the activities performed with this account.
    Description A description of the service account. This appears in the service accounts list.

    Choose a role for the service account that defines its permissions.

    • Administrator - Can perform all actions and view all tenant information.
    • Auditor - Can only perform GET actions on Activities.
    • Viewer - Can perform GET actions on all tenant information, but not create/modify.

    The status of the new service account.


    Select the check box to confirm that you want to create a service account.

  4. Click Save to create the .json file that is required to make the API calls, and save it on your computer. The .json file contains the following:

    • Service Account ID

    • Private key

    • DiscoveryURL

    The following example shows the contents of the .json file.

        "serviceAccountId": "11ea6140f94d5f82a3712de9ac6f6b24",
        "privateKey": "-----BEGIN RSA PRIVATE KEY-----MIIEowIBAAKCAQEAhmfhZYpMev5bfrFDCyJmvKIHPL/0OkDhTicXZHd37uhTK8MNzKdY2+ohApYbF/grS7U6+bLEBs2PoLd4Eqv/cj89CI5VCaZlf5jeHPM4mys39QpJ1ljo8PqJN/sn8ZUXG/CH6Nalx+3DRdYauXPLGOJ5p4w1HyGIPSLAzaUnrg8oE4xZmR1UVFDh8Zqv+ORVIlx4SdIxs8cLgKc2G2DYqQerig8a7fDrIsJeaRyjsFN451N45JVEpMEpkOCN7XDufgJrMSN1iPQXgi4ACLEpa1xVPdMYaTnrAJ3saU71i0afL+7i6x/lhF7GRAEskGG+LYQe8U+VBHHgtN7vLuHtvwIDAQABAoIBAAssze/MXOmJBoB1KpbdaF9ctW9Wom7JgDIoS+idikpB5NBpqlcOvvOh9tapNl1609a6ncmvFF9gbgW123Tp+hY8rc1tUCK6RAwk4KrViipUoJVuIo+A2vVWT1xpNHwAomg/Sn2Qgz4pRagj0hsDRqquAeFtZelNt28l2ZP/nFn7Z2bp7JK+XGbqd7j17CUCfbvXH7yQDTg34DjNRJ+U1DUToO5w9YPxuP5MjepDGsVKe64fEGFE9a8H4uGbSXBDHeNHRghOK+Htg3Rz6OrEd//2QBlv07p8wBiv4z+ZMBBpCkTXb5z+mXzXTKQv0fj6yfP3QlCjPQCHFbKNqsEFEikCgYEA2PgxkVeYoKPkxmihiRIV25XFJ94uKpdt9Jb5EwevQogGGMJMpysgy16fyPm5PpskHGCjHDEnr0OA6cA+Mo3d/fchLdDhYcTwNoLUrS9PG55xOC6RGGtYevQ+NOBWiEV4pkTB8TwuUI8jHzh+b1ZMkFkP5qx8x3GD9YCVNGyoVDUCgYEAnpV9eniJTJmAa54hpQyMqpT13CgvkmWiT/aHr77TGAk9zYDeyKkOYIFNX5p4EKOeqTfFzxWOPNIqsGfPvRF3HqTMmbaxmfxrvHKflwisw8j10oPqU1JIfJ5kUvj/9a18qcLVKXoIcGLNjZr4Iy9t4euDAXJefqgdH8sIgVzNEKMCgYAwFyL1chL0WB9XEs3rEcUifJnMcmSNMC9A7U2buDJSbs/bIQXYb6i/KuQDqcYzaDOizpCYqRSAtleWd/PRRLyVk/cYrpmmD/6mNm1pTXkdSAsURs4GOZTM++Hl2muTnMJXKBpMm+gwFunT+7OafehOfk8V89lcY366JZvsmMDemQKBgCjth+7dwQGl9EDSFPjV3lAAFdv1+yEbXeKpS6eN5kkjyXGKOvUqvG0nseJkqWwR7lbZ8BFcDNOhoibZBAJVyZp9Cdj6D6ggP2XpZ0rBkGUPLnJgXU+XwuF2t4m6fcTYO35MrFsCBb+LoGVVg4kBKqjN8YekDsM9fBbCfbV1T+9lAoGBAJ/xVihYF5JlQcQ2ISaLd8cHUXEH+WLklR0YyeV/EJB2TmoMji7+4oz2dILNwOXmcJZMPnrOPqGDyRv4UAIWrgRntfm4FsaV321PpE02yfujjXYUNGZcQRUJO5oex8sI8AJrPb4zQWYI6nxa6Y41l+cIJ7EFypEnndvsht/P6gRb-----END RSA PRIVATE KEY-----",
        "discoveryURI": ""

Create a JSON Web Token (JWT)

After you create the .json file in the SWS portal, and you have the Service Account ID and private key, do the following:

  1. Create a JSON Web Token (JWT). There are two ways to create a token; using the API token helper, or you can manually create the token.

  2. Call APIs using the Access Token received from the Authorization Server.

SWS authenticates clients with a Private Key JWT Client Authentication method (private_key_jwt), which is defined in OpenID Connect 1.0 and the JWT Profile for OAuth 2.0 Client Authentication specifications. This is an authentication method that can be used by clients to authenticate to the authorization server when using the token endpoint. Only clients that have registered a public key in the SWS portal (by creating a service account) and have signed a JWT using a matching private key (in the file downloaded when creating a Service Account) can authenticate.

When SWS authenticates clients with Private Key JWT Client Authentication, the clients send a request that contains an assertion in JWT format to the token endpoint of the server. SWS validates the signature and the payload of the assertion.

Recommendation: Although your application can complete these tasks by interacting directly with OAuth 2.0 using HTTP, server-to-server authentication interactions require applications to create and cryptographically sign JSON Web Tokens (JWTs). It is highly recommended to avoid any impact on the security of your application by using using libraries that abstract the cryptography away from your application code.

Automatically create a token using the API Token Helper

The simplest way to create an access token is by using the public-api-token-helper file. This token creator helper file is available from the CyberArk Marketplace.

Make sure you have Java installed on your computer; either OpenJDK, Oracle or Zulu.

To create an access token:
  1. Go to CyberArk Marketplace. Download the JAR file public-api-auth-helper-0.0.1-SNAPSHOT-application.jar.

  2. Open a terminal or command prompt and run the following command with the replaced values.

    java.exe -jar <path-to-public-api-auth-helper-0.0.1-SNAPSHOT-application.jar> -t <tenant ID> -p <path-to-secret-file>

    The syntax includes the following details:

    • The JAR file you downloaded from CyberArk Marketplace.

    • -t <tenant ID> - Enter your tenant ID value.

    • -p <path-to-secret-file> - Enter the service account secret file path that you received when you created your service account.

  3. After you run the command, look at the output for the access token.

  4. Copy and paste the token to the authorization header value in your request.

Manually create a token

After you create the .json file in the SWS portal, and you have the Service Account ID and private key, do the following:

  1. Create a JSON Web Token (JWT), which includes a header, a claim set, and a signature.

  2. Request an access token from the token endpoint of the SWS Authorization Server.

  3. Handle the JSON response that the Authorization Server returns.

The following sections describe each stage.

Generating the signed JWT

A JWT is composed of three parts: a header, a claim set, and a signature. The header and claim set are JSON objects. These JSON objects are serialized to UTF-8 bytes, then encoded using the Base64url encoding. The header, claim set, and signature are concatenated together with a period (.) character.

A JWT is composed of the following parts:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

Perform an access token request

After generating the signed JWT, an application can use it to request an access token.

This access token request is an HTTPS POST request, and must include the following parameters:








A signed JWT that contains information for client authentication

If the JWT and access token request are properly formed and the service account has permission to perform the operation, the JSON response from the Authorization Server includes an access token

Access tokens can be reused until during the duration noted in the expires_in value.


After your application obtains an access token, use the token to make calls to a SWS API on behalf of a service account. Include the access token in a request to the API by including an Authorization: Bearer <AccessToken> HTTP header. In most cases, you can use a client library to set up your calls to SWS APIs.