Preparations for API Authentication

    API Request URL

    The request URL of LINE WORKS Bot Platform APIs is as follows:

    • Live environment: https://apis.worksmobile.com/{API ID}/...
    • Testing environment: https://sandbox-apis.worksmobile.com/{API ID}/...

    Using an "API ID" makes your request URL different from others for each domain. You can find your API ID in the LINE WORKS Developer Console.

    Figure 3 API ID

    If your API ID has not been issued yet, click Get to get one. Put your API ID in the request URL as in the example below:

    • Live environment: https://apis.worksmobile.com/kr1wwTrYrbIot/...
    • Testing environment: https://sandbox-apis.worksmobile.com/kr1abeSbktS/...

    Service API

    Consumer Key

    A consumer key for the Service API is a value required to be included in the header when you make an API call. You can find your consumer key in the LINE WORKS Developer Console.

    Figure 4 Service API Consumer Key

    Figure 4 Service API Consumer Key

    If your consumer key has not been issued yet, click Get to get one.

    • You can specify the permission scopes of the Service API that you can use with your consumer key in Step 1. If you want the consumer key to be used for specific APIs only, please specify them. For categories of the Service API by permissions, refer to Service API Categories.
    • You can specify the validity period of the token that is issued with this consumer key in Step 2. The period can range from 7 to 365 days.
    • If You set the validity period to be automatically extended, it is extended whenever the token issued with this consumer key is used.
    • You can get up to 5 consumer keys.

    You can use the consumer key as in the example code below:

    PostMethod method = new PostMethod(url);
    method.setRequestHeader("consumerKey", "LQwDde6x8eV4ROOCOdSW");
    

    Authorization Code

    An authorization code is required to get an access token which should be included in the header when you make an API call. To get an authorization code, you need to make a request with the following request URL for login.

    Request URL

    • Live environment: https://auth.worksmobile.com/ba/{API ID}/service/authorize
    • Testing environment: https://sandbox-auth.worksmobile.com/ba/{API ID}/service/authorize

    HTTP Method

    GET

    Request

    Pass the following parameters using the GET method.

    Parameter Type Required Description
    client_id String Y A consumer key for the Service API (example: LQwDde6x8eV4ROOCOdSW)
    redirect_uri String Y The client's URL redirected after the authorization code is issued. It is URL encoded.
    state String Y A value used by the client to prevent CSRF.
    domain String Y Domain name (group name for Lite)

    Response

    If the LINE WORKS login page is displayed and the user successfully logs in, an authorization code is issued and redirected through the redirect_uri passed as a request parameter.

    If the user is already logged in LINE WORKS, an authorization code is issued and redirected through the redirect_uri without the login process.

    Parameter Type Required Description
    code String Y Authorization Code.
    An authorization code is used one time only, and expires within an hour.
    state String Y The state value passed when an authorization code is requested.

    Error

    When an invalid parameter or unavailable domain is used, or an internal error occurs, an error message is displayed.

    Access Token

    An access token is required to be included in the header when you call the Service API. You can use it as in the example code below.

    Caution

    • The authorization type must be "Bearer." Please make sure to put an empty space between "Bearer" and the token.
    PostMethod method = new PostMethod(url);
    method.setRequestHeader("consumerKey", "LQwDde6x8eV4ROOCOdSW");
    method.setRequestHeader("Authorization", "Bearer AAAAr1xaQrD3iGx2eyQ0/U3mu4OBJzC0HYNF");
    

    Request URL

    • Live environment: https://auth.worksmobile.com/ba/{API ID}/service/token
    • Testing environment: https://sandbox-auth.worksmobile.com/ba/{API ID}/service/token

    HTTP Method

    GET/POST

    Request

    Parameter Type Required Description
    client_id String Y A consumer key for the Service API (example: LQwDde6x8eV4ROOCOdSW)
    code String Y Authorization Code
    domain String Y Domain name (group name for Lite)

    Response

    Parameter Type Required Description
    errorCode String Y A response code for success or failure
    access_token String Y Access Token.
    A value required to be included in the header when making an API call.
    refresh_token String Y Refresh Token
    expire_in String Y Access token's expiration date

    Error Code

    Error code Description
    00 Success
    107 Parameter error
    502 Error in getting accessToken with code
    99 Unknown error

    Server API

    Consumer Key

    A consumer key for the Server API is a value required to be included in the header when you make an API call. You can find your consumer key in the LINE WORKS Developer Console.

    Figure 5 Server API Consumer Key

    Figure 5 Server API Consumer Key

    If your consumer key has not been issued yet, click GET to get one.

    • You can specify the permission scopes of the Server API that you can use with your consumer key in Step 1. If you want the consumer key to be used for specific APIs only, please specify them. For categories of the Server API by permissions, refer to Server API Categories.
    • You can specify the validity period of the token that is issued with this consumer key in Step 2. The period can range from 7 to 365 days.
    • If you set the validity period to be automatically extended, it is extended whenever the token issued with this consumer key is used.
    • You can get up to 5 consumer keys.
    • Once you delete your consumer key, values in the Server list (Fixed IP Style, ID Registration Style) associated with it are also deleted.

    You can use the consumer key as in the example code below:

    PostMethod method = new PostMethod(url);
    method.setRequestHeader("consumerKey", "dz0jtXyXc9Zo953HdjZA");
    

    Server Token

    A server token for the Server API is a value that is required to be included in the header when you make an API call. You can get your server token from the LINE WORKS Developer Console.

    There are two ways to get your server token: one is adding a static IP address, and the other is adding a server ID.

    Server Token (Fixed IP Style)

    Click Add on the Server List (Fixed IP Style) page, and the following page appears where you can add a static IP address to get a server token.

    Figure 6 Getting a Server Token

    Figure 6 Getting a Server Token

    • Enter a server name in Name.
    • Select a consumer key to associate from Select Key. Please note that the consumer key cannot be changed after a token is issued.
    • Enter an IP address of the server you want to use APIs for in IP and click GET to get a token. The server IP address you entered should be the valid one, in order to succeed in the API authentication process.
    • You cannot add multiple global IP addresses or an IP range.

    Once your server is successfully registered and a server token is issued, it is displayed on the Server List as in the figure below.

    Server Token (Fixed IP Style)

    Figure 7 Server Token (Fixed IP Style)

    Click the IP address, and you can get the token from the window that shows the details.

    Server Token (ID Registration Style)

    To get a server token, you can call the two-legged OAuth 2.0 API using a JSON Web Token (JWT RFC-7519), with a server ID that you can get from the LINE WORKS Developer Console as a parameter.

    How to Get a Server ID and Download a Private Key

    • Click ADD in Server List(ID Registration Style), and the page where you can get a token appears.
    • Enter a server name and select a consumer key, and you can get a 32-character server ID.
    • Download a private key of this server ID and save it.

    Figure 8 Adding a Server ID

    Figure 8 Adding a Server ID

    The following is an example of a server ID.

    f7eee8dbddd5430a96086068ab8b47d0
    

    The following is an example of a private key.

    -----BEGIN RSA PRIVATE KEY-----
    MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCePC4qTZPJVBeo
    IXTxkJx+Ny2Dg6mUSy5ec53Ennf6omFBctFZynKsG7/aJ4XFbkPBQskP4U9BBvSL
    6iBurLgQ7uAbXbRzqbso5+lLJH9Asw0kkkMSJggRY5jaQwfp4l63Ll3LEC0vrbjL
    SW4WFgPPBL1FyeHP9g06nkLINTHy++1csYXJXZqjkxNLYnx1Cdwj6+4L4q3HDqIn
    IxNzryPaZgOj54I851IZhoy2JgOjMyouRl40pjWBUEh/N4ijoqxCfC3ZXlQmb+a0
    A8fYyEhVmlL6mBMdgWdj9RiECXyy0Clmv5ZdTEzt4U7O482/nPmRh5stNyfx9QF9
    oEfDmx2xAgMBAAECggEAUJqHSbVK2vujMVoZoBPyI7knzh57e7bwX9y1OTsgEuQ0
    dopuajbeQx2/lPkdA30vtnq2wQgcvxsz5zHUY4xIFxgXwNjy2xhS5nt8M3Lb/7E1
    uLNoxw3ofjMl4cjTdyiA5v8PeCk9W1Q7FhLJqSZ9ui7H240DIlRMWNfVXPb8ArHR
    AjCB6gMIZhYDtQxq76mKxcVZgHnBB9I8dHcjvD+wfbGyX4H0RzTzCMNC4JrTKSIt
    y51GMma+jhZ86vcwPQs6bHPBrEbZOw1ZWVMHJOc40lkGj0KzU9jjhguXr6BITLtz
    HRrRFgdghpwdYTrUshLpCxJkK/I8UBUnXsAdISl7IQKBgQD155+FlO0Iy3htNS7E
    J/uHuC7ExEK01utHgKOoP0pSXmDBmUkAitr0xbvhpnxEEk6bBZdIdhuF/HeXRcJU
    T310PIRvIvtRq6bcK31UeelQKMRnp1I0ltj9J/+cutmScN9CbdqY2D9JoXCpk3h/
    grhvlmjr68lINtzU8GxSMhffiwKBgQCkuy2TS4eOZnDTxD3nUpqsJugrwBW/IydP
    ENhubhhIVUtBDPp/arFPDRJqfqgvjgeoY60L7mpo7uBWa4vwghFJBNDtRj2rKysK
    HTI3zaz9QT/7FtYyxCgFY2lijDVv1RVIM91V+aregYfdgeer4HI54Kcv2eNZ2rz0
    on6G809fMwKBgFC/DhK/JFaO+aximkivGFkokbLq/zyClh+UjijhH3aMpxjrTJ1w
    +xUFGPyvvn5bxJQC8fpJTiBhFqQFtBobQAa7GIGl6wCWbOQ/I5hpr8Myn8uplcTP
    A9GdIMJGWMtNZQJbMDygRafX6zbDxf2Y3xdFPI67jgy4dys1B1y2NkChAoGAcTnO
    y61gkTpMVuJOAk++zJE5h8jRqb0J6ciUWuMFgcJOpXm8PBQjp0g+3kAMbhNbpBxO
    9yJ6tYFrZTsqxrdAFkZfLJfZD2vue1cyCzUtsC1HQtihhedZ8sovx3LD0AhQRn6P
    peaj0aiKsG/3wyXUnX+SqstC/6Hfuu5ttWhLqA0CgYBTNRjoRdAJcKzlkdO5Pt/d
    Mm/NffywAmsaCrEigGHGs2Kgcz8D2ZrqU8SMUQJODIddAtA7IWHORIvbCIvd2ZHT
    k6DEtV+QtGpXZSsIwi6Dl62oive4nZ/9yGxWYRIXugvvVMcJVGQdH+INz5/9X30/
    j0+0lyfdNTYtuXlMebHUag==
    -----END RSA PRIVATE KEY-----
    

    How to Get a Server Token

    To get a server token, you should follow the procedure below:

    1. Create a JWT - RFC-7519
    2. Digitally sign the JWT - RFC-7515
    3. Request a token from the LINE WORKS authentication server - RFC-7523

    Figure 9 Sequence Diagram for Server Token Request

    Figure 9 Sequence Diagram for Server Token Request

    1. Create a JWT - RFC-7519

    JWT should be in the following form.

    {header BASE64 encoding}.{JSON Claim set BASE64 encoding}.{signature BASE64 encoding}
    
    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9
    .eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ
    .aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
    

    The RSA SHA-256 algorithm should be specified in the header.

    {"alg":"RS256","typ":"JWT"}
    

    After Base64-encoding the value, you can get a string as shown in the following example.

    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
    

    The JSON Claim Set has the following information:

    Parameter Description
    iss Server ID that you can get from the Developer Console
    iat JWT creation time.
    It is in Unix time format (in seconds).
    exp JWT expiration time.
    It is in Unix time format (in seconds).
    The difference between the iat and the exp (exp - iat) must not exceed 3600 seconds.

    For example, suppose the following:

    • Server ID: 46c4f281f81148c9b846c59262ae5888
    • JWT creation time: 2017-04-18 17:37:52
    • JWT expiration time: 2017-04-18 18:07:52 (after 30 minutes)

    The data in JSON format is as follows:

    {
      "iss":"46c4f281f81148c9b846c59262ae5888",
      "iat":1492504672,
      "exp":1492506472
    }
    

    The Base64-encoded string is as follows:

    eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ
    

    Combine the header and the Claim Set with "." and the {header BASE64 encoding}.{JSON Claim set BASE64 encoding} is as follows:

    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ
    

    2. Digitally sign the JWT - RFC-7515

    Comply with the JSON Web Signature (JWS RFC-7515) specification.
    Using the RSA SHA-256 algorithm (RS256 defined in the header), encrypt the byte array of the JWT header and body with the private key downloaded from the Developer Console, and Base64-encode it.

    Digitally sign and Base64-encode the {header BASE64 encoding}.{JSON Claim set BASE64 encoding} previously generated, and you can get the following {signature BASE64 encoding}.

    aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
    


    The following shows the completed JWT {header BASE64 encoding}.{JSON Claim set BASE64 encoding}.{signature BASE64 encoding}.

    eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ.aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
    

    Pass the JWT you just created with the assertion parameter when requesting a token.

    Note

    • There are libraries that help you create a JWT, so it is recommended to use one of them.
    • For JAVA, the following libraries are available:
      https://github.com/jwtk/jjwt
      https://github.com/auth0/java-jwt
      https://bitbucket.org/b_c/jose4j/wiki/Home
      https://bitbucket.org/connect2id/nimbus-jose-jwt/wiki/Home

    3. Request a token from the LINE WORKS authentication server - RFC-7523

    Request URL

    • Live environment: https://auth.worksmobile.com/b/{API ID}/server/token
    • Testing environment: https://sandbox-auth.worksmobile.com/b/{API ID}/server/token

    HTTP Method

    POST
    content-type : application/x-www-form-urlencoded; charset=UTF-8

    Request

    Pass the following parameters using the POST method.

    Parameter Type Required Description
    grant_type String Y A URL encoded string.
    urn:ietf:params:oauth:grant-type:jwt-bearer
    assertion String Y JWT
    POST /b/jp1PrJVEbjpFi/server/token HTTP/1.1
    Host: auth.worksmobile.com
    Content-Type: application/x-www-form-urlencoded; charset=UTF-8
    
    grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI0NmM0ZjI4MWY4MTE0OGM5Yjg0NmM1OTI2MmFlNTg4OCIsImlhdCI6MTQ5MjUwNDY3MiwiZXhwIjoxNDkyNTA2NDcyfQ.aICZ8qvYFKSJT6VdrmEcs6siCHaCgFkqpVs5VALKhf98sZjguppp-bOy9MpNlNepfSF0IyrdG3JavHLUYBz1NEVVZJwEm39f7gODmnt-_kGfDo1YtOqnclP1gM8oiObF2AH2Eneh3XuyeVeZbKAZmp6I_ZOf8AGayVVui61CsDPbUIPZSKUnbW1-vlXboTlojxJhvHznpYSNanHSrg5Nht2VO5sOeclEgPqg3J8Y6XOT60u8Morv5wHUy8a0QyO0yWCT5OJdXeVj94qfDAM15a1Puw9PfQOPm7QhOarvCJ8cOSqo9PHluq9-KZ1WXmfxSo-_itTb8y2YRT3kd21maQ
    

    Response

    Parameter Type Description
    access_token String Server Token
    token_type String Bearer
    expires_in String Server Token's validity period.
    The validity period is 24 hours (86400 seconds), and the token automatically expires after that period.
    However, if you enable "Token Automatic extension" of the Server API Consumer Key in the Developer Console and use the Server API within 24 hours, the token's validity will be automatically extended by 24 hours from the moment the API is used.
    {
       "access_token":"AAAA/KM+LBNADalmequDgJsBc6pt9o+c2VydmVySWQ+vDbccdzZjec5Hy+dWnUz79laysFBlEg1MmzLuu/6/4l61R4yZTWlGrYcv2KjPPS4JfmYGDctUa95bxP+/YLGk+bVTPt/SjhLCpFnJnrltTmkMLPgrrGxDWM1gJ1tM8y4oBBJWfccN45SfjINOG9wwSAdF7r7+XykkmrcF9AGL1c7hufaVJAl6/ErtkidUXkdW3Dd5QYHm97XOj5n1pWmtJ4+IrAlsKqGqKlUcvRRMHes06s6FD+4pUv7JXnuWnx6/BVqaloeDFCU3vD4jfUOn2UQNIJakvcxknwiCqvoNtcjUzQ58oQ4IG0YWNltI=",
       "token_type":"Bearer",
       "expires_in":86400
    }
    

    Caution

    • The access_token automatically expires unless you use it within 24 hours. Therefore, you should get a new token once a day if you're using ID Registration Style.
    • Store the time you get your access_token and the token information, and use them to check the validity of the token, whether it expires or not, when using the Server API.

    Error

    An error occurs when there is no access_token for a response.
    The following example shows a response returned when a JWT that has expired or an invalid parameter is passed.

    {
        "message":"jwt already expired",
        "detail":"JWT expired at 2017-04-19T13:57:58Z. Current time: 2017-04-19T14:27:52Z,
         a difference of 1794480 milliseconds.  Allowed clock skew: 0 milliseconds.",
        "code":"31"
    }
    

    How to Use a Server Token

    You can use the server token as in the example code below.

    Caution

    • The authorization type must be "Bearer." Please make sure to put an empty space between "Bearer" and the token.
    PostMethod method = new PostMethod(url);
    method.setRequestHeader("consumerKey", "dz0jtXyXc9Zo953HdjZA");
    method.setRequestHeader("Authorization", "Bearer AAAA5IdUiCj5emZowcf49VRu7qbb548g6aGE");