Authentication Service API

Anaplan • anaplanauthentication
Help

Apiary Powered Documentation

Sign in with Apiary account.

Authentication Service API

Introduction

To use the version 2.0 API, you must send requests using an Anaplan authentication (auth) token. This is in the form of a JSON Web Token. This must be in the Authorization header of the API request. For example: Authorization:AnaplanAuthToken {anaplan_auth_token} Where {anaplan_auth_token} is replaced with your auth token.

The Authentication Service API enables you to:

  • Create an auth token

  • Get the details of an existing {anaplan_auth_token}

  • Refresh an auth token by generating a new one from the existing {anaplan_auth_token} you provide

API use requirements

As a best practice for using our APIs, you should be familiar with RESTful APIs and any specific requirements for the action you are performing. For more information, see Anaplan API Requirements.

Reference

Auth Token

Create an Auth Token with a username and password

/token/authenticate

  • To use the version 2.0 API, you must use an Anaplan auth token generated from the Anaplan Authentication Service.

  • You can get an auth token generated using a certificate from a recognized external public certificate authority (CA) or with your login and password.

  • Then use the auth token in your API requests.

  • Note: If your workspace uses single sign-on (SSO), you must be assigned as an Exception User to use basic auth and obtain an Anaplan auth token. For more information on exception users in Anaplan, see Assign Exception Users in Anapedia.

Create an auth token using a username and password

  • Use your Anaplan username and password to generate an auth token.

  • Then use this auth token in your API requests.

Note: If your workspace uses single sign-on (SSO), your user must be assigned as an Exception User to use basic auth and obtain an Anaplan auth token. For more information on exception users in Anaplan, see Assign Exception Users in Anapedia.

Request

curl -X POST --user Username@Company.com:YourPassword https://auth.anaplan.com/token/authenticate
Note: curl automatically encodes Base64 for you.
Headers

Authorization:Basic encoded_username:password (this must be Base64 encoded.)

  • A custom script requires that you encode the username:password with Base64.

  • Note: In basic HTTP auth, a request contains a header field in the form of Authorization: basic credentials, where the credentials are the Base64 encoding of ID and password joined by a single colon :.

Response 200 (application/json)

{
    "meta": {
        "validationUrl": "https://auth.anaplan.com/token/validate"
    },
    "status": "SUCCESS",
    "statusMessage": "Login successful",
    "tokenInfo": {
        "expiresAt": 1493036651173,
        "tokenId": "9aa99999-1111-11a2-b333-abc11223ab12",
        "tokenValue": "aBCDdefghilMnz30PrD8Iw==.twOZw6fT+ttckbx5Ap3TRvjAAgqHY4UrgkRLiyvQppI8ULyPCc59GNimzco4pBXaMM8wEJ1yrJE6C4Vd6GflfjdUVhGpaji4oG+NBzVnBvA+bBfFnmwWsOiL/8kge+cFxqbW+XqLAAHz3aRV6WgB7wYGXP/0AYant1VKAHFLcnSzRtJqeKakW+rnbUf6eHDQWsF/7AhfG7PJ6qDS8zm8JMjWSZdb0WsOzr79A/IcL1tu4iyn2n9gKA6l9cOhPhYT3AEQJE4GCtLA9eEYILBTbKC4LWuxgnmo+G8VkAIsBoAy8dcSRBPXHZMKRZ5ssmpO766zOZqpdkcX0RcH2dwKUqZefwNrfhdoKy5rmi54/LU93YVYv/d/Mm8HyfV9sWkfEKvFHGM1v+PmCQJLh/CQvHtdu5fd6Had4L0arKa574XsUb07mwKau53Xn+iBBcDu.0CpRsu37FpDizsfXVCxOQ7iLBjJM6+72hczGl4+3RQ4=",
        "refreshTokenId": ""3ab11111-2222-33e4-a111-01a1b222cd3a"
    }
}

Create an auth token using Certificate Authentication

To create an AnaplanAuthToken:

  1. Use a Certificate Authority (CA) issued X509 certificate to generate an auth token.

  2. Use this auth token in your API requests.

  3. In the header, replace {your_CA_certificate} with the base64-encoded certificate in PEM format.

  4. Replace {encoded_string} with a base-64 encoded randomly generated string (of at least 100 bytes).

  5. Replace {encoded_signed_string} with the previous string signed by your private key and then base-64 encoded. Note: We currently only support the SHA512withRSA algorithm when you sign with your private key.

See the code sample below for more details on generating random encoded strings.
For more information on CA certificates, see Tenant Administration: Certificates in Anapedia.

Java code sample

    Generating {your_CA_certificate} 
                String generateEncodedCert(String certFile) throws IOException {
                    byte[] certBytes;
            
                    try (FileInputStream fileInputStream = new FileInputStream(certFile);
                         BufferedInputStream bis = new BufferedInputStream(fileInputStream)) {
            
                        certBytes = new byte[(int) new File(certFile).length()];
                        bis.read(certBytes);
                    }
            
                    return Base64.getEncoder().encodeToString(certBytes);
                }
    
    Generating {encoded_string} and {encoded_signed_string}
    
                Pair<String, String> generateStrings(String privateKeyFile) throws Exception {
                    byte[] privKeyBytes;
            
                    try (FileInputStream fileInputStream = new FileInputStream(privateKeyFile);
                         BufferedInputStream bis = new BufferedInputStream(fileInputStream)) {
            
                        privKeyBytes = new byte[(int) new File(privateKeyFile).length()];
                        bis.read(privKeyBytes);
                    }
            
                    RSAPrivateKey privKey = (RSAPrivateKey) KeyFactory.getInstance("RSA").generatePrivate(
                            new PKCS8EncodedKeySpec(privKeyBytes));
            
                    SecureRandom random = new SecureRandom();
                    random.setSeed(System.currentTimeMillis());
            
                    byte bytes[] = new byte[100];
                    random.nextBytes(bytes);
            
                    byte[] decodedSignedData = sign(privKey, bytes);
            
                    String encodedData = Base64.getEncoder().encodeToString(bytes);
                    String encodedSignedData = Base64.getEncoder().encodeToString(decodedSignedData);
            
                    return new ImmutablePair<>(encodedData, encodedSignedData);
                }

                private byte[] sign(PrivateKey privateKey, byte[] dataBytes) throws NoSuchAlgorithmException, InvalidKeyException, SignatureException {
                    Signature sig = Signature.getInstance("SHA512withRSA");

                    sig.initSign(privateKey);
                    sig.update(dataBytes);

                    return sig.sign();
                }

Request

curl -X POST -H authorization:'CACertificate {your_CA_certificate}' -H "Content-Type:application/json" -d '{"encodedData": {encoded_string},
"encodedSignedData" : {encoded_signed_string}} https://auth.anaplan.com/token/authenticate
Headers

Authorization:CACertificate {your_CA_certificate}

Body
            {
                "encodedData": "{encoded_string}",
                "encodedSignedData" : {encoded_signed_string}
            }

Response 200 (application/json)

{
    "meta": {
        "validationUrl": "https://auth.anaplan.com/token/validate"
    },
    "status": "SUCCESS",
    "statusMessage": "Login successful",
    "tokenInfo": {
        "expiresAt": 1493036651173,
        "tokenId": "9aa99999-1111-11a2-b333-abc11223ab12",
        "tokenValue": "aBCDdefghilMnz30PrD8Iw==.twOZw6fT+ttckbx5Ap3TRvjAAgqHY4UrgkRLiyvQppI8ULyPCc59GNimzco4pBXaMM8wEJ1yrJE6C4Vd6GflfjdUVhGpaji4oG+NBzVnBvA+bBfFnmwWsOiL/8kge+cFxqbW+XqLAAHz3aRV6WgB7wYGXP/0AYant1VKAHFLcnSzRtJqeKakW+rnbUf6eHDQWsF/7AhfG7PJ6qDS8zm8JMjWSZdb0WsOzr79A/IcL1tu4iyn2n9gKA6l9cOhPhYT3AEQJE4GCtLA9eEYILBTbKC4LWuxgnmo+G8VkAIsBoAy8dcSRBPXHZMKRZ5ssmpO766zOZqpdkcX0RcH2dwKUqZefwNrfhdoKy5rmi54/LU93YVYv/d/Mm8HyfV9sWkfEKvFHGM1v+PmCQJLh/CQvHtdu5fd6Had4L0arKa574XsUb07mwKau53Xn+iBBcDu.0CpRsu37FpDizsfXVCxOQ7iLBjJM6+72hczGl4+3RQ4=",
        "refreshTokenId": ""3ab11111-2222-33e4-a111-01a1b222cd3a"
    }
}

Get auth token details

/token/validate

Gets information on a provided {anaplan_auth_token}. If the token is valid, returns the details of the {anaplan_auth_token}. If the token is invalid, returns a 401 Unauthorized message.

Request

curl GET -H authorization:'AnaplanAuthToken {anaplan_auth_token}' https://auth.anaplan.com/token/validate

Headers

Authorization:AnaplanAuthToken {anaplan_auth_token}

Response 200 (application/json)

{
    "meta": {
        "validationUrl": "https://auth.anaplan.com/token/validate"
    },
    "status": "SUCCESS",
    "statusMessage": "Token validated",
    "userInfo": {
        "userGuid": "8a89d9999f3c7099015f999d5208458a",
        "userId": "a.user@anaplan.com",
        "customerGuid": "8a80d99a5bf97b99995c3d1577610415"
    },
    "tokenInfo": {
        "expiresAt": 1509728252000
        "tokenId": "4d677e7d-c0ae-11e7-9f79-b179910b5099",
    }
}

Refresh auth token

/token/refresh

Generates a new auth token from an existing {anaplan_auth_token} that you provide. You need to refresh your token if your session runs for longer than 30 minutes.

Request

            curl -X POST -H authorization:'AnaplanAuthToken {anaplan_auth_token}' https://auth.anaplan.com/token/refresh

Headers

Authorization:AnaplanAuthToken {anaplan_auth_token}

Response 200 (application/json)

{
    "meta": {
        "validationUrl": "https://auth.anaplan.com/token/validate "
    },
    "status": "SUCCESS",
    "statusMessage": "Token refreshed",
    "tokenInfo": {
        "expiresAt": 1509725972924,
        "tokenId": "4d688e7d-c0ae-11e7-9f69-b170010b5016",
        "tokenValue": "wOlfU2tLezUAkmLY/C5lXw==.CH9fWgnDiN099USFFAWrrtoCoqVS/xixNtG4V0Vk6f2zVAa/lTmjJsHeSxSXAW9HRH2EA+q7rLzmtWvkdi8dtOv/hExmpNRfTtux/9t8RXVFmNMxro+tPbhfE/MUPSiaxzyRlSYkpph8WFIWKlrLhZ0Iw/iweuSIlAwVtXhbsDt674T5GiJxS35wh1h5ateeylU/1Y3Het+YR5F/8idr1oZu5cd+SE16tHLUPJQwp5uGkfTTBp5CR/zv4wzIsY35wGpgEAgUC4F19zASo6/EB6Br2KmyqJEmUIWmFJRRk9qmjJpS05FHUTXVpU5d2psrRRGUh1XNLoOOnz7DopuhTS4TwiI3AJeNYca3IfeGQo7LyfAmsTc4QL6xsQh5M6G5q/+wfNFY1zHVxSf/nugfHJOBRUnLMUgs46/TMWTqhMoweFsMG84uI0eHA3SAAiFQ.63GpdlW8HpciJq24dr4klBCog1TEIkTj6NBS+iPM4uY=",
        "refreshTokenId": "95ee4c30-c0ae-11e7-be10-c9ac36e86de2"
    }
}

Log out the user

/token/logout

Deletes an {anaplan_auth_token}. After the /logout command, the {anaplan_auth_token} is deleted and no longer valid.

Request

curl -X POST -H authorization:'AnaplanAuthToken {anaplan_auth_token}' https://auth.anaplan.com/token/logout

Header

Authorization: AnaplanAuthToken {anaplan_auth_token}

Response 204 (application/json)