Authentication
The following instructions describe how to authenticate to the public facing APIs of the GSCS custody platform.
Connecting to GSCS APIs
GSCS supports API integration to our services with third-party applications via the OAuth 2.0 standard for authentication.
OAuth access must be approved by GSCS. Once an OAuth application is approved for use, GSCS issues a clientId and clientSecret through Lockbox or via secure email.
The clientId is used in your application to authorize the user to access GSCS APIs.
For more information on how to request access to our APIs, contact the GSCS Integrations Team.
Note
The clientSecret isn’t retained by GSCS staff and must be safeguarded by the vendor
Step 1 - Configure GSCS Authorization URL
Once you've obtained your clientId, you need to configure the GSCS User Authorization URL copied below in your application.
Users must click this link to authorize GSCS to share their data with your application. The user is redirected back to your site once they have completed the authorization.
Note
You will need to provide a redirect URL to the GSCS Integrations team to configure.
https://uat.advisorsolutions.gs.com/app/authorizations/[Your Client Id]
This is a one time authorization to give the user access to the Oauth app. Access can be revoked by the user in the users setting page.
GSCS REST clients can take actions based on the endpoints permissioned for your specific integration and the entitlements of the user authorizing the data sharing in this step. The levels of access for each permission type is broken down in the table below.
Levels of Account Access
| Summary Viwer | Detail Viewer | Money Mover | Trader | Trader & Money Mover | Account Manager | |
|---|---|---|---|---|---|---|
| View Account Summary | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| View settings and Account Details | ✓ | ✓ | ✓ | ✓ | ✓ | |
| Transfer Money | ✓ | ✓ | ✓ | |||
| Transfer and Trade Securities | ✓ | ✓ | ✓ | |||
| Vote Corporate Actions | ✓ | |||||
| Edit Account Settings | ✓ |
Step 2 - Get Client Credentials Token
Make a GET call to the Ping Federate token endpoint to obtain the access_token:
curl -u <clientId>:<clientSecret> --data "grant_type=client_credentials" https://idfs-qa.gs.com/as/token.oauth2?access_token_manager_id=JwtOneGsApiA response generates to indicate your call was successful:
{"access_token": "<redacted>",
"token_type": "Bearer",
"expires_in": 43199}Note
The client credentials token will expire after 8 hours. You will need to generate a new token after this period.
Step 3 - Generate User accessToken
Make a POST call to the GSCS OAuth endpoint to obtain the user token for the Advisor. You must pass the access_token you obtained in Step 2 in the Authorization header of this request.
curl --request POST "https://uat-custody.advisorsolutions.gsapis.com/api/v2/oauth-apps/[clientId]/tokens" --header "Authorization: Bearer <access_token>" --header "Content-Type: application/json" -d "{ \"loginId\": \"testloginId\"}"The GSCS user must have already granted access to share data with the 3rd party application (see step 1). If the user has not authorized access, the API returns an error.
{"type":"UNAUTHORIZED",
"displayMessage":"Clientid 2a98a33fc85b4616974955321c30728b is not authorized to get tokens for loginid testloginid",
"requestId":"a0eebb1dd67741bfaa841c7ce2816ef0",
"timestamp":"2024-02-13T12:11:33.283312035-05:00"}A successful call will return the accessToken you need to make the API calls to GSCS for this user.
{"accessToken":"[YOUR_BEARER_TOKEN_HERE]"}Note
This access token is valid for 20 minutes before it expires. Once the access token expires, you’re required to generate a new one.
Step 4 - Use accessToken to call the GSCS APIs
Provide the accessToken obtained in Step 3 in the Authorization header for any subsequent API calls until the token expires.
Sample request for GET Users:
GET "https://uat-custody.advisorsolutions.gsapis.com/api/v2/users/testadvisor" -H
"Authorization: Bearer [YOUR_BEARER_TOKEN_HERE]"If successful, the API returns a 200 HTTP code with a response body similar to the following example:
{
"userId": "testadvisor",
"serviceTaskId": null,
"taskId": null,
"guid": null,
"folioLoginId": "testadvisor",
"idhubLoginId": null,
"memberOid": "5116089184397476264",
"firstName": "FN-testadvisor",
"middleName": "J",
"lastName": "LN-testadvisor",
"suffix": null,
"loginId": "testadvisor",
"email": "advisor@gs.com",
"recoveryEmail": null,
"dayPhoneNumber": 723637272,
"eveningPhoneNumber": 7466960799,
"deliveryMethod": "EMAIL",
"residentialAddress": null,
"mailingAddress": null,
"dateOfBirth": "1962-11-22",
"tid": "123456789",
"countryOfCitizenship1": "US",
"countryOfCitizenship2": null,
"permanentUsResident": null,
"residentStatus": null,
"dependentCount": 0,
"maritalStatus": null,
"topMarginalTaxBracket": null,
"employmentStatus": null,
"directorOrTenPercentShareholder": null,
"directorOrTenPercentShareholderCompany": null,
"finraAssociatedPerson": null,
"politicallyExposedPerson": null,
"sourcesOfWealth": null,
"employmentDetails": null,
"assetsDetails": null,
"personalInvestmentsDetails": null,
"entrepreneurDetails": null,
"expectedActivitiesInvestmentProducts": null,
"anticipateDomesticWireTransfers": null,
"estimatedNumberOfDomesticWireTransfersPerMonth": null,
"anticipateWritingChecksAgainstAccount": null,
"estimatedNumberOfChecksWrittenPerMonth": null,
"firmOid": 4395513243606464000,
"firmId": "TESTARANXVJTWCFI",
"partnerCode": "TESTADVISOR",
"paymentOid": "0",
"folioEmployeeInd": "N",
"creationMode": "E",
"memberAgreement": "Y",
"folioStatus": null,
"transState": "REGISTERED_MEMBER",
"membershipType": "INVESTMENT_ADVISOR",
"folioExpirationDate": "3999-12-31 05:00:00",
"folioMemberChangeTs": "2021-10-07 04:00:00",
"driversLicense": null,
"creationDate": null,
"advisorLoginId": null,
"accreditedInvestorAnnualIncome": null,
"accreditedInvestorNetWorth": null,
"cipStatus": null,
"firmIds": [
"TESTARANXVJTWCFI"
],
"roles": null,
"newRoles": null,
"previousExperienceIndustrySector": null,
"previousPrivatePlacementExperience": null,
"status": "ACTIVE",
"tokens": [
"userId:testadvisor"
],
"memberRelationships": [],
"entitlements": {
"view": [
"role:superuser"
],
"edit": [
"role:superuser"
],
"admin": [
"role:superuser"
],
"openAccounts": [
"role:superuser"
]
}
}
Was this page useful?
Give feedback to help us improve developer.gs.com and serve you better.