OAuth External API Guide

Aconex Web Services

Aconex OAuth2 Services

Get OAuth Status

Initiate OAuth Access Code Request
Get OAuth Access Token
Refresh OAuth Access Token

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

Related APIs

Initiate OAuth Access Code Request

Get OAuth Access Token
Refresh OAuth Access Token

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=ahuss

@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 Problem accessing /as/authorization.oauth2. Reason: Unknown or invalid client_id 400
client_id

NO_UNIQUE_USER_FOUND Returned if provided email doesn’t exist or there are multiple users found for specified 302
email.

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.

Related APIs

Get OAuth Status

Get OAuth Access Token
Refresh OAuth Access Token

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

Note: The “auth server hostname” can be retrieved using the API service “Get OAuth Status”
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-qWyWWpDbposDS

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":"eyJhbGciOiJSUzI1N

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

Related APIs

Get OAuth Status

Initiate OAuth Access Code Request

Refresh OAuth Access Token

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":"eyJhbGciOiJSUzI1N

Error Codes Specific to this Service

Status Code Description Http Status Code

Prerequisites

Need valid refresh token

Constraints

None

Related APIs

Get OAuth Status

Initiate OAuth Access Code Request
Get OAuth Access Token