Legacy OAuth Developer Guide

Oracle Aconex OAuth Policy

Configuration Item	Oracle Aconex Standard Value	Description / Notes
OAuth Access Token Expiry	1 Hour	The Access Token (AT) is valid for one hour. When an AT is refreshed, new (AT, RT) are provided.
OAuth Refresh Token Expiry	1 Week	A Refresh Token (RT) is used to obtain a new AT. A valid RT can be used to obtain new (AT, RT) even if the current AT has expired.  If (AT, RT) aren’t refreshed within the RT expiry period then the user would have to re-authenticate.
OAuth Refresh Grant Expiry	Never	When the refresh grant expires then the user has to re-authenticate regardless of the RT validity.

Get OAuth Status

This service checks if OAuth2 authentication is enabled on the selected hostname and returns the authorization server hostname.

URL structure

HTTP GET: https://{hostname}/OAuthStatus

 

Parameters

There are no query parameters required for this service

 

Sample request

HTTP GET: https://au1.aconex.com/OAuthStatus

 

Response Fields

Element	Type	Cardinality	Notes
uri	String	1	Authorization server hostname
enabled	Boolean	1

Note: The response is in JSON format

 

Sample response

{"uri":"https://sso-au1.aconex.com:443","enabled":true}

Error Codes Specific to this Service

Status Code

Description

Http Status Code

Prerequisites

None

Constraints

None listed for this service

Initiate OAuth Access Code Request

This request is done in an Internet Browser for security reasons. After successful authorization by the user this request returns an access code that can be exchanged into an access token.  

URL structure

HTTP GET: https://{hostname}/Logon

 

Parameters

Parameters	Type	Cardinality	Notes
Action	String	1	Value=”StartOAuth”
client_id	String	1	Issued by Aconex
redirect_uri	String	1	Valid template issued by Aconex
email	String	0..1	User email address. Only used for SSO enabled accounts.

 

Sample request

HTTP GET: https://au1.aconex.com/Logon?Action=StartOAuth&client_id=apitest&redirect_uri=http%3A%2F%2Flocalhost%3A8089%2Fcallback&email=ahussein@aconex.com

 

Response Fields

Element	Type (length)	Cardinality	Notes
code	String(40)	0..1	Valid for 60 seconds. Available if authentication was successful.
error	String	0..1	Available if authentication was unsuccessful

Note: The response is sent with a HTTP 302 status code, a redirect to the used return uri

Sample response

GET http://localhost:8089/callback?code=D4CU3dHfRaSwWowrCMGmljLsLssGXDYp_n-ubQAD HTTP/1.1

GET http://localhost:8089/callback?error= NO_UNIQUE_USER_FOUND HTTP/1.1

 

Error Codes Specific to this Service

Status Code	Description	Http Status Code
Error 400 Invalid redirect_uri	Problem accessing /as/authorization.oauth2. Reason: Invalid redirect_uri	400
Error 400 Unknown or invalid client_id	Problem accessing /as/authorization.oauth2. Reason: Unknown or invalid client_id	400
NO_UNIQUE_USER_FOUND	Returned if provided email doesn’t exist or there are multiple users found for specified email.	302
SO_IS_DISABLED	OAuth2 authentication is disabled on the selected hostname.	302

Note: Responses with Http Status Code 302 is returned to the specified return uri, see sample above.

Prerequisites

Valid client id and return uri. For SSO (Single Sign On) requests, valid email is needed.

Constraints

The returned access code is only valid for 60 seconds.

Get OAuth Access Token

This service returns an access token in exchange of a valid access code. A valid access token can be used with Aconex Web API services requiring authorization.

URL structure

HTTP POST: https://{auth server hostname}/as/token.oauth2

 

Interface

HTTP Request Header variables

If the optional field “client_secret” is used, it needs to be added through a request header together with the “client_id”. The two fields are Base64 encoded using “client_id” as username and the “client_secret” as password. Use the header key “Authorization”. If this header is provided, the “client_id” as request field can be omitted.

 

Sample Header

Authorization: Basic YXBpdGVzdDphcGl0ZXN0

 

Request Fields

Field name	Type (length)	Cardinality	Notes
grant_type	String	1	Value=”authorization_code”
client_id	String	0..1	Same used retrieving the code. Omitted if used with client_secret header.
redirect_uri	String	1	Same used retrieving the code
code	String(40)	1

 

Sample request

HTTP POST: https://sso-au1.aconex.com/ as/token.oauth2? grant_type=authorization_code&client_id=apitest&redirect_uri=http%3A%2F%2Flocalhost%3A8089%2Fcallback&code=KLczbdoGX6YraA-qWyWWpDbposDS7DSHYamDWgAC

 

Response Fields

Element	Type (length)	Cardinality	Notes
token_type	String	1	Value = “Bearer”
expires_in	Integer	1	Value in seconds
refresh_token	String(42)	1
access_token	String(481)	1

Note: The response is in JSON format

Sample response

{"token_type":"Bearer","expires_in":86399,"refresh_token":"y3KZkGwvP4CCnXBkHqUoDXuRHkO4NyLP0QIRM5WQDE","access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJlbWFpbCI6InN2ZW5iIiwiZXhwIjoxNDQwNTc4NjEyLCJzY29wZSI6W10sImNsaWVudF9pZCI6ImFwaXJlZmVyZW5jZWFwcCJ9.d02KNjtZ7XOjT-uRoF6MLCWj7nILBC8fznm-3kH0a8KRmSaVEf0ppOpS1BKK1GMGbDL-FNTmIhzer0UEICKSbC3sjVjOL0gnNbFud0XXiKXfVkIaJaaCBOpCyGJH2WsvDbJhRMEuCTuX98Gc5SAt1uJNPZNNvgUx7-qqFUIzsDodSXRZ8TiyIyfZ-UsYbW9RCHsYZqPMXkVtqIncOiz9jCA8BI08zRHdqkZRAnksa3f2iaoGRODId5NqaXZgnuRzGaY66KmieFiDx0HpbJmRsZpmI5Z1_5Pz2s6WBXKTq5KQZjyw6fO2SBJ37JCwFTbCBGStYJGo8q-ZuwH4_kmR5w"}

 

Error Codes Specific to this Service

Status Code	Description	Http Status Code
invalid_grant	Authorization code is invalid or expired	400
invalid_client	Invalid client or client credentials	401

Prerequisites

Valid client id and return uri.

Constraints

Valid access code

Refresh OAuth Access Token

This service return a new access token in exchange of a valid refresh token. By using this service, the access token can be renewed indefinitely unless the user’s granted access is revoked.

URL structure

HTTP POST: https://{auth server hostname}/as/token.oauth2

 

Interface

HTTP Request Header variables

If the optional field “client_secret” is used, it needs to be added through a request header together with the “client_id”. The two fields are Base64 encoded using “client_id” as username and the “client_secret” as password. Use the header key “Authorization”. If this header is provided, the “client_id” as request field can be omitted.

 

Sample Header

Authorization: Basic YXBpdGVzdDphcGl0ZXN0

Request Fields

Field name	Type (length)	Cardinality	Notes
grant_type	String	1	Value=”refresh_token”
refresh_token	String(42)	1

 

Sample request

HTTP POST: https://sso-au1.aconex.com/ as/token.oauth2? grant_type=refresh_token&refresh_token=lxQxbnBdq0fReUfzpzunrpuqzyJW6MRwX0zAqfahrg

 

Response Fields

Element	Type (length)	Cardinality	Notes
token_type	String	1	Value = “Bearer”
expires_in	Integer	1	Value in seconds
refresh_token	String(42)	1
access_token	String(481)	1

Note: The response is in JSON format

Sample response

{"token_type":"Bearer","expires_in":86399,"refresh_token":"y3KZkGwvP4CCnXBkHqUoDXuRHkO4NyLP0QIRM5WQDE","access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJlbWFpbCI6InN2ZW5iIiwiZXhwIjoxNDQwNTc4NjEyLCJzY29wZSI6W10sImNsaWVudF9pZCI6ImFwaXJlZmVyZW5jZWFwcCJ9.d02KNjtZ7XOjT-uRoF6MLCWj7nILBC8fznm-3kH0a8KRmSaVEf0ppOpS1BKK1GMGbDL-FNTmIhzer0UEICKSbC3sjVjOL0gnNbFud0XXiKXfVkIaJaaCBOpCyGJH2WsvDbJhRMEuCTuX98Gc5SAt1uJNPZNNvgUx7-qqFUIzsDodSXRZ8TiyIyfZ-UsYbW9RCHsYZqPMXkVtqIncOiz9jCA8BI08zRHdqkZRAnksa3f2iaoGRODId5NqaXZgnuRzGaY66KmieFiDx0HpbJmRsZpmI5Z1_5Pz2s6WBXKTq5KQZjyw6fO2SBJ37JCwFTbCBGStYJGo8q-ZuwH4_kmR5w"}

 

Error Codes Specific to this Service

Status Code

Description

Http Status Code

Prerequisites

Need valid refresh token

Constraints

None

Note: The OAuth Access Token Tool has been deprecated due to security and compliance concerns. Please use other publicly available HTTP tools such as Postman or curl to fetch OAuth tokens for your integration testing purposes.