Skip to main content

2-1 Authentication

Retrieve access tokens

This API retrieves an access token that allows access to SVF Cloud using the clientID, secret, and keyFile (secret key).

Example 1. Endpoint URI
https://api.svfcloud.com/oauth2/token


Example 2. HTTP method

POST



Example 3. Content-type header for the HTTP request

application/x-www-form-urlencoded



Example 4. Parameters

  • Request body

    Request body data

    Value

    Required

    Description

    grant_type

    urn:ietf:params:oauth:grant-type:jwt-bearer

    maru.png

    assertion

    JWT bearer token

    maru.png

    See "Create a JWT bearer token".

  • Request header

    Header field

    Value

    Description

    Authorization

    Basic {base64 encoded clientID:secret}

    Specify the result of Base64 encoding for the clientId combined with the secret.



Response

Code

Description

HTTP/1.1 200 OK

Indicates that the process was executed successfully.

HTTP/1.1 401 Unauthorized

Occurs if the authentication information is invalid.

HTTP/1.1 403 Forbidden

Occurs if the execute permission is not assigned.

HTTP/1.1 429 Too many Requests

Occurs if the number of API calls exceeds the threshold. Execute again after the number of seconds passed for the value returned in "Retry-After" of the response header.

HTTP/1.1 503 Service Unavailable

Occurs if a valid service plan or point does not exist.

Example 5. Output example (JSON format)
{"token":"fa074d728eef1bfb1da897de1f64b53dae7857e87dd0b8b96d9f65e06da43e9f","expiration":1442046911540}

Key

Content

Description

token

Access token

The access token for using SVF Cloud WebAPI. This token should be assigned in the request header when the API is called.

expiration

Expiration time

The time at which the access token expires (elapsed time in seconds since 1970-01-01T0:0:0Z in UTC). Past this time limit, the access token will be disabled and re-authentication will be required. When you are performing a process that will take a long time (e.g., downloading an artifact), we recommend that you check the remaining duration and, if necessary, retrieve the token again so that it does not expire during the process.



Create a JWT bearer token

SVF Cloud uses a JWT bearer token for authentication.

Use the following procedure to create a JWT bearer token:

  1. Create the JWT header in the following format: {"alg":"RS256"}

  2. Use Base64 to encode the JWT header. The result will look like the following: "eyJhbGciOiJSUzI1NiJ9".

  3. Use iss, sub, exp, userName, timeZone, and locale to create a JSON request set for JWT (timeZone and locale are optional).

    {
  "iss": "SVFFEQQUGPSITUHVRAOMBRPUXMRXQKER",
  "sub": "xxxx@api.svfcloud.com",
  "exp": "1333685628",
  "userName": "John Smith",
  "timeZone": "Asia/Tokyo",
  "locale": "ja"
}

    Field

    Example

    Description

    iss

    SVFFEQQUGPSITUHVRAOMBRPUXMRXQKER

    Specify the clientId.

    sub

    xxxx@api.svfcloud.com

    Specify the user ID. The user information specified here is displayed in the Activity History in SVF Cloud Manager.

    exp

    1333685628

    Specify the time when the access token will expire (elapsed time in seconds since 1970-01-01T0:0:0Z in UTC).

    userName

    John Smith

    Specify the user name. The user information specified here will be reflected in the "Author" PDF property.

    timeZone

    Asia/Tokyo

    This setting is optional. Specify the time zone. The time zone information specified here will be reflected in the following.

    • "Creation Date" in the PDF properties.

    • The outputs of the following functions by the SVF output engine:

      • DATE

      • IDATE

      • TIME

      • ITIME

    locale

    en

    This setting is optional. Specify locale. You can specify any locale (regional information) different from the execution environment.

  4. Use Base64 to encode the JWT request set with no line breaks.

  5. Create a new string for the encoded JWT header and an encoded JWT request set in the following format:

    encoded_JWT_Header + "." + encoded_JWT_Claims_Set

  6. Use RSA SHA256 to sign the result string.

  7. Join the stings in the following format:

    encoded_JWT_Header + "." + encoded_JWT_Claims_Set + "." + base64_encoded_signature

Reference

For details, download and check the following sample program related to retrieving and discarding an access token: "Authentication.java".

Discard access tokens

This API discards the specified access token.

Caution

If you archive a PDF file to the cloud version of invoiceAgent Documents, do not discard the token until the print is complete (normal or abnormal termination).

Example 6. Endpoint URI
https://api.svfcloud.com/oauth2/revoke


Example 7. HTTP method

POST



Example 8. Content-type header for the HTTP request

application/x-www-form-urlencoded



Example 9. Parameters

  • Request body

    Request body data

    Value

    Required

    Description

    token

    Access token

    maru.png

    Specify the access token to discard.

  • Request header

    Header field

    Value

    Description

    Authorization

    Bearer {your access token}

    Specify the access token retrieved via authentication.



Response

Code

Description

HTTP/1.1 204 No Content

Indicates that the process was executed successfully.

HTTP/1.1 400 Bad Request

Occurs if the request content is invalid.

HTTP/1.1 401 Unauthorized

Occurs if the authentication information is invalid.

HTTP/1.1 429 Too many Requests

Occurs if the number of API calls exceeds the threshold. Execute again after the number of seconds passed for the value returned in "Retry-After" of the response header.

In this section: