Getting Started

Topics:

·        Prerequisites

·        Authentication 

·        Supported Methods

·        Supported Headers

·        Status Code

Prerequisites

·        Access to the Accounting Foundation Cloud Service.

·        Appropriate User Privileges to access the services.

·        Technical and Functional knowledge to understand and execute the REST APIs and configuration knowledge.

·        Knowledge of REST Concepts, JSON, and browser-based REST Client.

·        Knowledge of interactive and automatic tools to verify the APIs such as Postman and Command Line Interfaces (CLI).

Obtain Account Information

The account creation email from Oracle contains the Identity Domain Name for the Accounting Foundation Cloud Service Instance. If you do not have this information, then contact your Service Administrator.

Authentication

The Authentication Process involves the use of cURL Commands in a CLI Tool to generate the access token and invoke REST APIs. The Authentication Token is generated through the OAuth Client ID and Secret Credentials created in IAM/IDCS during Provisioning. The Authentication Token does not require that you log in to the AFCS Application to invoke the REST APIs from external applications.

Ensure that you have the appropriate log-in credentials to access the Accounting Foundation Cloud Service and the appropriate roles to perform specific operations using the API Resources. The following is the list of steps for Authentication and further subsections provide the details:

1.     Download the Application Certificate

2.     Get the OAuth Client ID and Client Secret

3.     Generate the Access Token

4.     Invoke the API using the Access Token

Download the Application Certificate

The Application Certificate is required for verification purposes when you use cURL commands. You may choose not to download the certificate if you plan to turn off the cURL Certificate Verification and use an insecure connection (if you add the --insecure Flag to the cURL command).

To download the Application Certificate, do as follows:

1.     Log in to the AFCS Application.

2.     Click the View site information/Verified by Icon in the Browser URL Address Bar.

3.     Select More information.

Figure: Certificates - More Information

4.     Click View Certificate and then click PEM(cert) to download the certificate.

Figure: Download PEM (cert) 

Get the OAuth Client ID and Client Secret

To get the OAuth Client ID and Client Secret, follow these steps:

1.     Enter the IDCS URL in the Browser's URL Address Bar.

The Oracle Cloud Account Sign In Window appears.

2.     Log in to Oracle Identity Cloud Service (IDCS).

3.     Select the Navigation Icon to view a list of available functions.

4.     Select Oracle Cloud Services.

For more information, see Access Service Consoles from Administering Oracle Identity Cloud Service.

5.     From the Oracle Cloud Services Window, select the required AFCS Internal Application Service (in AFCS <tenant-id> INTERNAL Format) from the list.

Figure: AFCS <tenant_id> INTERNAL

NOTE:   

If the AFCS <tenant-id>INTERNAL Applications are not available, select AFCS <tenant-id>.

6.     Click the Configuration Tab.

The Client ID and Client Secret Details are displayed in the General Information Section.

Figure: Client ID and Client Secret 

7.     Copy the Client ID and Client Secret.

8.     Open a CLI Tool.

9.     Generate the Access Token as shown in the following section.

Generate the Access Token

To generate the Access Token, add the Client ID, Client Secret, User Name, and Password using cURL Commands in the CLI Tool. The following is an example:

echo -n "<tenant_oauth_app_client_id>:<tenant_oauth_app_client_secret>" | base64 -w 0      (generates basic base64 encoded authorization token)

curl -H "Authorization: Basic <base64 encoded tenant_oauth_app_client_id:tenant_oauth_app_client_secret>"

 -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"  --request POST

https://<idcs-URL.identity>.<TENANT>.com/oauth2/v1/token

 -d "grant_type=password&scope=urn:opc:idm:__myscopes__&username=<username>&password=<password>"

echo -n "<PROD_APP_ID_INTERNAL>" | base64 -w 0

curl -H "Authorization: Basic <Basic_Auth_Token>

 -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"  --request POST

https://<idcs-URL.identity.TENANT.com/oauth2/v1/token

 -d "grant_type=password&scope=urn:opc:idm:__myscopes__&username=<UserName>&password=<Password>"

After generating the Access Token, invoke the API as shown in the following section.

Invoke the API using the Access Token

To invoke the API using the generated Access Token, do as shown in the following example using cURL Commands in the CLI Tool:

curl -iL -H "Authorization: Bearer <access token>" -H "Content-Type: <content_type>" -d "<request_body>" --cacert <certificate(.pem)> -X <http_verb> <api_url>

curl -iL -H "Authorization: Bearer <AUTH_TOKEN>"

-H "Content-Type: application/json" -d "{\"type\":\"files\",\"data\":[{\"fileName\":\"testtoken\",\"mimeType\":\"text/plain\",\"fileSize\":

123}]}" --cacert outcert.pem -X POST https://<OCI-URL>/<TENANT><APP_ID>/dsa/utils/getObjStoreParUrl

Supported Methods

·        GET:  Retrieve information about the service instance.

·        POST: Create, scale, backup, start, and stop the service instance.

Media Types

The following media type is supported by the Accounting Foundation Cloud Service REST APIs:

·         application/json

Supported Headers

The REST API supports headers that may be passed in the header section of an HTTP Request or Response.

The following table provides information about supported headers.

Status Code

When you call the Accounting Foundation Cloud Service REST APIs Resources, the Response Header returns one of the standard HTTP Status Codes.

The following table lists the common HTTP Response Codes.

                                     Table:   Status Code