Help Center/ Cognitive Engagement Center/ API Reference/ Interface Authentication Modes/ C3 OIAP Interface Authentication
Updated on 2023-09-27 GMT+08:00
View PDF
Share

C3 OIAP Interface Authentication

Description

When the OIAP provides interfaces for internal system or third-party access, the token obtaining interface needs to be invoked to obtain the token and the validity period of the token. The token is carried in the business interface invoked later. If the validity period of the token expires, the token obtaining interface needs to be invoked again.

Interface Method

POST

URL

https://IP:PORT/oifde/rest/api/gettoken

Request

Table 1 Parameter in the request header

No.

Parameter

Type

Mandatory

Description

1

Content-Type

String

Yes

The value is fixed at application/json; charset=UTF-8.
Table 2 Parameters in the request body

Parameter

Type

Position

Mandatory

Description

appKey

String

Body

Yes

App key. The value is the tenant ID.

appSecret

String

Body

Yes

App secret, which must be agreed by both parties and can be dynamically changed.

How do I obtain appKey and appSecret?

  1. Check whether the OIAP needs to interconnect with a tenant (third-party system), a third-party system (such as iFLYTEK ASR), or an internal system (such as the AICC or CSP).
  2. If a tenant (third-party system) needs to be interconnected, obtain a token using the tenant ID and invoke the interface within the token validity period. The obtained token must be passed for each interface invocation. The request body of the interface must contain authToken.
    • Set appKey to the tenant ID. After signing in to the tenant space, you can use the browser development tool to view cookies and obtain the value of TenantId.
    • Set appSecret to the value of API Password on the API Password Settings tab page on System Management > System Configuration page in the IVR.
  3. If a third-party system needs to be interconnected, obtain a token using the default user specified for system interconnection and invoke the interface within the token validity period. In addition, the obtained token must be passed for each interface invocation. The request header of the interface must contain appkey (username) and authToken (token).
    Currently, only the interface described in Offline Conversion Callback Interface can be invoked in this authentication mode.
    • Set appKey to the machine-machine communication account provided by the ODFS functioning as the server for the third-party system. The account is configured during ODFS installation. Generally, the value is ODFS_SYS_OPENAPI.
    • Set appSecret to machine-machine communication password provided by the ODFS functioning as the server for the third-party system, which is configured during installation.
  4. If an internal system (the AICC or CSP) needs to be interconnected, obtain a token using the default user specified for system interconnection and invoke the interface within the token validity period. In addition, the obtained token must be passed for each interface invocation. The request header of the interface must contain appkey (username) and authToken (token).
    • Set appKey to the username for accessing the machine-machine interface provided by the ODFS, which is configured during ODFS installation. Generally, the value is ipcc.
    • Set appSecret to the password provided by the ODFS for accessing the machine-machine interface server. The password is configured during installation.

Response

Parameter

Type

Position

Mandatory

Description

errorCode

Integer

Body

Yes

Error code.

  • 0: success
  • Other values: failure

    The status code 200 also indicates success.

errorMsg

String

Body

No

Error description.

authToken

String

Body

Yes

Authentication token.

expireTime

Integer

Body

No

Token validity period, in seconds. The default value is 3600 seconds.

If the error code is not 0, no value is returned.

Example

  • Request body 
    {
   "appKey": "tenant001",
   "appSecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" 
}
  • Response body 
    {
    "errorCode" : 0, //Error code, which is an integer. If no error is reported, the value is 0.
    "errorMsg" : "", //Error message, which is a string. If no error is reported, this parameter is left empty.
    "authToken": "2************************", 
    "expireTime" : 3600
}