Overview

This service provides a SOAP alternative to the RESTful oauth2token service, and is used to acquire an OAuth 2 Token that can be used by an OAuth 2 Authenticated User of a Client App for access to Projector services. Note that this service should not be provided with a SessionTicket on invocation. Note also that if the response has a non-null value for RedirectUrl , the service was invoked on the incorrect server and must be re-invoked on the server specified in RedirectUrl .

For more information on implementing OAuth 2, refer to the OAuth 2.0 Client Application Developer Guide.

Request Format

PwsAcquireOauth2Token Request

PwsAcquireOauth2Token
- serviceRequest: PwsAcquireOauth2TokenRq
  - RequestId: Int32
  - SessionTicket: String
  - ClientIdentifier: String
  - ClientSecret: String
  - Code: String
  - CodeVerifier: String
  - GrantType: String
  - RedirectUri: String
  - RefreshToken: String

Request Elements

Element	Data Type	Required?	Description	Sample Data
RequestId	Int32	No	Click here for more information
SessionTicket	String	No	Should be omitted or set to null.
ClientIdentifier	String	Yes	Guid string that identifies the client app requesting a token	24748faf-e239-d132-167a-6e4d3e1bd0fb
ClientSecret	String	Yes	Secret string that client app uses to prove itself	r6tuVhR3ol1BFFVfy3Oe-J8VoH0KpkgLVqAMi-IIgvd_Lr613IEYcXhKAea8eLtQKSIgQ4jHIKhCKQcwriUtgB
Code	String	When GrantType="code"	The short-lived authentication code that was provided on the successful redirect of the `oauth2authorize` request. Must be supplied if GrantType="code" and may not be supplied for any other GrantType.	E2BgYJjLoNrEY50z-8hLMXevukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA
CodeVerifier	String	No	Code Verifier generated by the client app and for which a code challenge was previously sent as part of the `oauth2authorize` request that was implementing PKCE. May only be supplied if GrantType="code", and must be supplied if a code challenge was part of the authorization request that generated the code.	swubMxS7yR-SYjlEwuu5gaS8~bvgL-ngbpZiYFLR_4Vf~u388c.qimhmm6kVc3h3h~TSmhDj02AIPeGcI_Y
GrantType	String	Yes	Currently must be either "code" for an initial grant, or "refresh_token" for a token refresh.
RedirectUri	String	When GrantType="code"	Must be identical to the `redirect_uri` that was supplied as part of the `oauth2authorize` request.	https://my.app.com/redirect-handler
RefreshToken	String	When GrantType="refresh_token"	A valid refresh token that designates a client app connection needing a refresh	E2BgYJjLoNrEY50z-7gMN1evukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA

Request Usage Example(s)

Request for OAuth 2 Token on initial authentication grant by code

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsAcquireOauth2Token>
         <pws:serviceRequest>
            <req:ClientIdentifier>24748faf-e239-d132-167a-6e4d3e1bd0fb</req:ClientIdentifier>
            <req:ClientSecret>r6tuVhR3ol1BFFVfy3Oe-J8VoH0KpkgLVqAMi-IIgvd_Lr613IEYcXhKAea8eLtQKSIgQ4jHIKhCKQcwriUtgB</req:ClientSecret>
            <req:Code>E2BgYJjLoNrEY50z-8hLMXevukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA</req:Code>
            <req:CodeVerifier>swubMxS7yR-SYjlEwuu5gaS8~bvgL-ngbpZiYFLR_4Vf~u388c.qimhmm6kVc3h3h~TSmhDj02AIPeGcI_Y</req:CodeVerifier>
            <req:GrantType>code</req:GrantType>
            <req:RedirectUri>https://my.app.com/redirect-handler</req:RedirectUri>
         </pws:serviceRequest>
      </pws:PwsAcquireOauth2Token>
   </soapenv:Body>
</soapenv:Envelope>

Request for OAuth2 Token Refresh

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pws="http://projectorpsa.com/PwsProjectorServices/" xmlns:req="http://projectorpsa.com/DataContracts/Requests/">
   <soapenv:Header/>
   <soapenv:Body>
      <pws:PwsAcquireOauth2Token>
         <pws:serviceRequest>
            <req:ClientIdentifier>24748faf-e239-d132-167a-6e4d3e1bd0fb</req:ClientIdentifier>
            <req:ClientSecret>r6tuVhR3ol1BFFVfy3Oe-J8VoH0KpkgLVqAMi-IIgvd_Lr613IEYcXhKAea8eLtQKSIgQ4jHIKhCKQcwriUtgB</req:ClientSecret> 
            <req:GrantType>refresh_token</req:GrantType>
            <req:RefreshToken>E2BgYJjLoNrEY50z-7gMN1evukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA</req:RefreshToken>
         </pws:serviceRequest>
      </pws:PwsAcquireOauth2Token>
   </soapenv:Body>
</soapenv:Envelope>

Response Format

PwsAcquireOauth2Token Response

PwsAcquireOauth2TokenResponse
- PwsAcquireOauth2TokenResult: PwsAcquireOauth2TokenRs
  - Messages: PwsMessage[]
  - ResponseId: Int32
  - Status: RequestStatus
  - ServerTimestampUtc: DateTime
  - AccessToken: String
  - ExpiresInSeconds: Int32
  - MaxLifetimeMinutes: Int32
  - RedirectUrl: String
  - RefreshToken: String
  - RestServiceAuthority: String
  - SoapServiceAuthority: String
  - TimeoutMinutes: Int32
  - TokenType: String
  - Scope: String

Response Elements

Element	Data Type	Description	Sample Data
Messages	PwsMessage[]	The web service response status and message. Click here for more information.
ResponseId	Int32	Click here for more information
Status	RequestStatus	Click here for more information
ServerTimestampUtc	DateTime	Click here for more information
AccessToken	String	Token used for subsequent API access to Projector. In practical terms, this is a SessionTicket.	Af4yzv6CcFKZEh2dz45zZg==
ExpiresInSeconds	Int32	How many seconds the `AccessToken` is valid for.	604800
MaxLifetimeMinutes	Int32	The maximum lifetime of the `AccessToken` in minutes.	10080
RedirectUrl	String	If this is set, this `PwsAcquireOauth2Token` service invocation was made against the incorrect server for the user being authenticated. If that is the case, the service should be re-invoked against this base URL.	https://secure2.projectorpsa.com
RefreshToken	String	The token that can be used to refresh the client app user's access when the Access Token is expired.	E2BgYJjLoNrEY50z-7gMN1evukfd3EWpZcn5RQW6xemGeYelfl_aetMDAA
RestServiceAuthority	String	The URL that must be used for any restful reporting services invoked with the `AccessToken` .	https://app2.projectorpsa.com
SoapServiceAuthority	String	The base URL that must be used for any SOAP services invoked with the `AccessToken` .	https://secure2.projectorpsa.com
TimeoutMinutes	Int32	How long the `AccessToken` may be valid with no use in minutes.	10080
TokenType	String	`projector_session_ticket`	projector_session_ticket
Scope	String	Scope granted to this token, which may be fewer than those requested in the intitial authentication request, but never more. Please note that if no scope was requested, the value here will be an empty string. Null is reserved for when the token itself is null because the incorrect server was hit.	V:maintainCostCenters U:maintainUsers enterTime

Response Usage Example(s)

OAuth 2 Token Response when request is to correct server

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsAcquireOauth2TokenResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsAcquireOauth2TokenResult xmlns:a="http://projectorpsa.com/DataContracts/Responses/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/> 
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">0</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2021-12-08T15:50:51.1940528Z</ServerTimestampUtc>
            <a:AccessToken>Ab2C5oN9uZnVCAOt4STUaA==</a:AccessToken>
            <a:ExpiresInSeconds>604800</a:ExpiresInSeconds>
            <a:MaxLifetimeMinutes>10080</a:MaxLifetimeMinutes>
            <a:RedirectUrl i:nil="true"/>
            <a:RefreshToken>ASgA1_8QAAAAIv-lrk_NEdOPhr3ts0Ks2wtyZXZjb3JwLXNnMdXn_IJiutlI</a:RefreshToken>
            <a:RestServiceAuthority>http://app2.projectorpsa.com</a:RestServiceAuthority>
            <a:SoapServiceAuthority>http://secure2.projectorpsa.com</a:SoapServiceAuthority>
            <a:TimeoutMinutes>10080</a:TimeoutMinutes>
            <a:TokenType>projector_session_ticket</a:TokenType>
            <a:Scope/>
         </PwsAcquireOauth2TokenResult>
      </PwsAcquireOauth2TokenResponse>
   </s:Body>
</s:Envelope>

OAuth 2 Token Response when request is to incorrect server

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Body>
      <PwsAcquireOauth2TokenResponse xmlns="http://projectorpsa.com/PwsProjectorServices/">
         <PwsAcquireOauth2TokenResult xmlns:a="http://projectorpsa.com/DataContracts/Responses/" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
            <Messages xmlns="http://projectorpsa.com/CommonServices/" xmlns:b="http://projectorpsa.com/DataContracts/Shared/Common/"/>  
            <ResponseId xmlns="http://projectorpsa.com/CommonServices/">0</ResponseId>
            <Status xmlns="http://projectorpsa.com/CommonServices/">Ok</Status>
            <ServerTimestampUtc xmlns="http://projectorpsa.com/CommonServices/">2021-12-08T16:07:26.5261911Z</ServerTimestampUtc>
            <a:AccessToken i:nil="true"/>
            <a:ExpiresInSeconds i:nil="true"/>
            <a:MaxLifetimeMinutes i:nil="true"/>
            <a:RedirectUrl>https://secure2.projectorpsa.com</a:RedirectUrl>
            <a:RefreshToken i:nil="true"/>
            <a:RestServiceAuthority i:nil="true"/>
            <a:SoapServiceAuthority i:nil="true"/>
            <a:TimeoutMinutes i:nil="true"/>
            <a:TokenType i:nil="true"/>
            <a:Scope i:nil="true"/>
         </PwsAcquireOauth2TokenResult>
      </PwsAcquireOauth2TokenResponse>
   </s:Body>
</s:Envelope>

PwsAcquireOauth2Token - Common Errors and Warnings

For all errors and warnings please refer to the Complete List of Errors and Warnings

ErrorNumber	ErrorCode	ErrorText
50629	OauthUnsupportedGrantType	Unsupported OAuth2 Grant Type "{GrantType}".
50630	OauthInvalidClient	Invalid Oauth2 Client.
50631	OauthInvalidGrant	Invalid Grant for Oauth2 Token: "{InvalidReason}".
50632	OauthInvalidRequest	Invalid OAuth2 Request in Context "{Context}". Null or missing parameters "{Missing}". Improper parameters "{Improper}".
50635	OauthUnsupportedTokenType	Unsupported OAuth2 Token Type "{TokenType}".

[data-colorid=uqbl1z9o66]{color:#333333} html[data-color-mode=dark] [data-colorid=uqbl1z9o66]{color:#cccccc}Overview