All AuctionACCESS APIs use the OAuth protocol for application and user authorization. OAuth is the industry standard for assuring your online transactions are secure, and you must provide a valid access token for each request you make. OAuth access tokens verify to AuctionACCESS that a request is coming from a valid application and that the application has the user's authorization to carry out the requests.

Minting Access Tokens

The AuctionACCESS token service generates, or mints, access tokens via client credentials grant. The client credentials grant flow mints a new application access token that you can use to access the resources owned by the application.

Configuring the Request

You need to configure three parts of a client credentials grant request:

• The target endpoint
• The HTTP request headers
• The request payload

Setting the Target Endpoint

The endpoint you use depends on the environment you are targeting.

OAuth Token-Request Endpoints

Sandbox

POST https://auctionaccess.oktapreview.com/oauth2/default/v1/token

Production

POST https://auctionaccess.okta.com/oauth2/default/v1/token

Configuring the HTTP Request Headers

Set the following HTTP request headers:

• Content Type – Must be set to: application/x-www-form-urlencoded
• Authorization – The word “Basic” followed by your base64-encoded OAuth credentials (:)

Configuring the Request Payload

Format the payload of your POST request with the following values:

• Set grant_type to client_credentials
• Set scope to api

The client_credentials Grant Request

The client_credentials grant is a single request that mints a new application access token. Use the token to make requests to API methods that match the scopes configured into the access token. Configure your request using the following call specifics:

Call specifics
            HTTP method: POST
            URL (Sandbox): https://auctionaccess.oktapreview.com/oauth2/default/v1/token
            HTTP headers:
            Content-Type = application/x-www-form-urlencoded
            Authorization = Basic <B64-encoded_oauth_credentials>
            
            Request body:
            Select x-www-form-unrelencoded
            
            Enter keys and corresponding values:
            grant_type = client_credentials
            scope = api
            

cURL Request for Token

Base64-encode the client ID and secret and then pass through the /token endpoint. Please refer to the next section for instructions on how to base64-encode.

curl --request POST
--url https://auctionaccess.oktapreview.com/oauth2/default/v1/token
--header 'accept:application/json'
--header 'authorization: Basic YOUR_ACCESS_KEY'
--header 'cache-control: no-cache'
--header 'content-type: application/x-www-form-urlencoded'
--data 'grant_type=client_credentials&scope=api

If the credentials are valid, the application receives an access token:

{
    "access_token": "eyJ...1LQ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "api"
}

Access token must be included in authorization header for all the API requests.

Base64-encode the Client ID and Secret

Use this section to base64-encode the client ID and secret. When you finish encoding, you can then include the encoded client ID and secret in the HTTP authorization header in the following format:

authorization: Basic <base64 encoded client ID and secret>

If you are using macOS or Linux:

1. Obtain client ID and secret by contacting AuctionACCESS.
2. Launch your preferred text editor, then paste the client ID and secret into a new file.
3. Place the client ID and secret on the same line, and insert a colon between them: clientid:clientsecret
4. Copy the clientid:clientsecret line to the clipboard.
5. Launch a terminal and enter the following command, replacing clientid:clientsecret with the value that you just copied:
   1. echo-n clientid:clientsecret | base64
6. Copy the returned value.

Note: If the returned value is broken into more than one line, return to your text editor and make sure the entire result is on a single line with no text wrapping.

If you are using Windows:

1. Obtain client ID and secret by contacting AuctionACCESS.
2. Launch your preferred text editor, then paste the client ID and secret into a new file.
3. Place the client ID and secret on the same line, and insert a colon between them: clientid:clientsecret
4. Save the file to C:\temp and name the file appCreds.txt.
5. In Windows Explorer, right-click C:\temp, and then select CMD Prompt Here from the context menu.
6. Enter the following command to encode the client ID and client secret:
   1. certutil -encode appCreds.txt appbase64Creds.txt
7. Locate and open appbase64Creds.txt in C:\temp, copy its contents, and then close the file.

Note: Delete the appCreds.txt and the appbase64Creds.txt files after you finish.

Error Responses

If content type is not set or is not application/x-www-form-urlencoded as described in the document

{
    "errorCode": "E0000021",
    "errorSummary": "Bad request. Accept and/or Content-Type headers likely do not match supported values.",
    "errorLink": "E0000021",
    "errorId": "oaeQI4A8paXTWKfrRLc0lyRnQ",
    "errorCauses": []
} 

If scope is not set as described in the document

{
    "error": "invalid_scope",
    "error_description": "The authorization server resource does not have any configured default scopes, 'scope' must be provided."
}

If grant type is not set as mentioned in document

{
    "error": "invalid_request",
    "error_description": "The token request must specify a 'grant_type'. Valid values: [client_credentials]"
}

If credentials are incorrect

{
    "errorCode": "invalid_client",
    "errorSummary": "No client credentials found.",
    "errorLink": "invalid_client",
    "errorId": "oaer7rwFUEGSQS_XCQ592lynA",
    "errorCauses": []
}

Every response implements the baseResponse interface which contains two properties:

• statusCode: Enum representing the status of the request
• errorDetails: Error object with more detail as to what issue(s) was encountered

For a full list of possible error codes, view the ErrorCode enum.

Sample Responses

SUCCESS

{
    "data": {
        "validatePerson": {
            ...,
            "statusCode": "SUCCESS",
            "errorDetails": null
        }
    }
}

NO_OPERATION

{
    "data": {
        "validatePerson": {
            ...,
            "statusCode": "NO_OPERATION",
            "errorDetails": null
        }
    }
}

BAD_REQUEST

{
    "data": {
        "validatePerson": {
            ...,
            "statusCode": "BAD_REQUEST",
            "errorDetails": [
                {
                    "errorCode": "VALIDATION_ERROR",
                    "field": [
                        "auctionId"
                    ],
                    "message": [
                        "Invalid Auction Id"
                    ]
                }
            ]
        }
    }
}

FAILURE

{
    "data": {
        "validatePerson": {
            ...,
            "statusCode": "FAILURE",
            "errorDetails": [
                {
                    "errorCode": "INTERNAL_SERVER_ERROR",
                    "field": null,
                    "message": [
                        "An unexpected error occurred while attempting to validate the passed person.  Please try again"
                    ]
                }
            ]
        }
    }
}

Standard Request & Responses

When possible, all validate calls should include the auctionId parameter in order to ensure you receive all specific issues relative to the person or company under consideration. Validate calls should also include the isValid parameter in the request in order to receive a Boolean indicating if the requested entity is valid.

GraphQL is case-sensitive, so ensure that query and mutation names, as well as field names, match exactly with the documentation. If your request does not follow the documented format, you will receive a GraphQL error in response.

Person Validate

Typically, clients use this flow to gather the minimum required person data to then register the person with AuctionACCESS.

Query

query validatePerson {
  validatePerson(auctionAccessId: "123456789", last4PhotoId: "1234") {
    person {
      id
      name {
        first
        last
      }
      birthDate
      roles {
        companyId
        role
        company {
          dealer {
            legalName
            companyName
          }
          issues {
            created {
              createdDateTime
              creatorId
            }
            createdComment {
              comment
              created {
                createdDateTime
                creatorId
              }
              createdByCompany
              id
              restrictionCommentId
              globalVerified
              subject
              verifiedUserId
            }
            creationUserHomeCompanyId
            id
            issueEffectiveDate
            issueType {
              association
              allowPublicResolution
              callToResolve
              created {
                  createdDateTime
                  creatorId
              }
              displayNameEnglish
              description
              displayNameFrench
              instructionsEnglish
              displayNameSpanish
              id
              selfResolve
              scope
              instructionsSpanish
              instructionsFrench
            }
            referenceId
            locked
            requestedInfo {
              documentDescription
              requiredByCountry
              requiredByState
            }
            restrictionCompanyId
            resolved
            restrictionCompanyName
            visibility
          }
        }
      }
    }
    issues {
      created {
        createdDateTime
        creatorId
      }
      createdComment {
        comment
        created {
          createdDateTime
          creatorId
        }
        createdByCompany
        id
        restrictionCommentId
        globalVerified
        subject
        verifiedUserId
      }
      creationUserHomeCompanyId
      id
      issueEffectiveDate
      issueType {
        association
        allowPublicResolution
        callToResolve
        created {
          createdDateTime
          creatorId
        }
        displayNameEnglish
        description
        displayNameFrench
        instructionsEnglish
        displayNameSpanish
        id
        selfResolve
        scope
        instructionsSpanish
        instructionsFrench
      }
      referenceId
      locked
      requestedInfo {
        documentDescription
        requiredByCountry
        requiredByState
      }
      restrictionCompanyId
      resolved
      restrictionCompanyName
      visibility
    }
    isValid
    statusCode
    errorDetails {
      errorCode
      field
      message
    }
  }
}

Response

{
  "data": {
    "validatePerson": {
      "person": {
        "id": "1000000123",
        "name": {
          "first": "John",
          "last": "Doe"
        },
        "birthDate": "2024-01-01",
        "roles": [
          {
            "companyId": "5000000123",
            "role": "Test",
            "company": {
              "dealer": {
                "legalName": "abc123",
                "companyName": "abc123"
              },
              "issues": [
                {
                  "created": {
                    "createdDateTime": "2024-01-01 23:59:59.997",
                    "creatorId": 123456789
                  },
                  "createdComment": {
                    "comment": "abc123",
                    "created": {
                      "createdDateTime": "2024-01-01 23:59:59.997",
                      "creatorId": 123456789
                    },
                    "createdByCompany": "1000000123",
                    "id": "12345678",
                    "restrictionCommentId": null,
                    "globalVerified": false,
                    "subject": "abc123",
                    "verifiedUserId": null
                  },
                  "creationUserHomeCompanyId": "1000000123",
                  "id": "12345678",
                  "issueEffectiveDate": "2024-01-01",
                  "issueType": {
                    "association": "Person",
                    "created": {
                      "createdDateTime": "2024-01-01 23:59:59.997",
                      "creatorId": 123456789
                    },
                    "description": "abc123",
                    "scope": "abc123"
                  },
                  "referenceId": "1234567",
                  "locked": false,
                  "requestedInfo": {
                    "documentDescription": "abc123", 
                    "requiredByCountry": null,
                    "requiredByState": null
                  }
                }
              ]
            }
          }
        ]
      },
      "issues": [
        {
          "created": {
            "createdDateTime": "2024-01-01 23:59:59.997",
            "creatorId": 123456789
          },
          "createdComment": {
            "comment": "abc123",
            "created": {
              "createdDateTime": "2024-01-01 23:59:59.997",
              "creatorId": 123456789
            },
            "createdByCompany": "abc123",
            "id": "4",
            "restrictionCommentId": null,
            "globalVerified": true,
            "subject": "abc123",
            "verifiedUserId": null
          },
          "creationUserHomeCompanyId": "5",
          "id": "6",
          "issueEffectiveDate": "2024-01-01",
          "issueType": {
            "association": "Person",
            "created": {
              "createdDateTime": "2024-01-01 23:59:59.997",
              "creatorId": 123456789
            },
            "description": "abc123",
            "scope": "NA"
          },
          "referenceId": "7",
          "locked": false,
          "requestedInfo": {
            "documentDescription": "abc123",
            "requiredByCountry": "United States",
            "requiredByState": "Alabama"
          }
        }
      ],
      "isValid": true,
      "statusCode": "BAD_REQUEST",
      "errorDetails": [
          {
            "errorCode": "INVALID_PERSON_ID",
            "field": "auctionAccessId",
            "message": [
                "Invalid Person ID."
            ]
          }
      ]
    }
  }
}

Person Register

After making use of personValidate to collect the minimum required person data, typically clients then make use of a multi-select control in their UI to select the dealers they want to register and then use this aggregated data to populate the personRegister request(s).

Mutation

mutation MyMutation {
              personRegister(auctionAccessId: "123456789", auctionId: "9876543210", companyId: "12345678") {
                person {
                  id
                  name {
                    first
                    last
                  }
                  birthDate
                  roles {
                    company {
                      id
                    }
                  }
                }
                registrationStatus {
                  personRoleStatus {
                    reason
                    status
                    auctionAccessId
                    auctionId
                    auctionName
                  }
                  companyStatus {
                    reason
                    status
                    auctionId
                    auctionName
                  }
                }
                statusCode
                errorDetails{
                  errorCode
                  field
                  message
                }
              }
            }
            
            

Response

{
  "data": {
    "personRegister": {
      "person": {
        "id": "123456789",
        "name": {
          "first": "Jane",
          "last": "Doe"
        },
        "birthDate": "2024-01-01",
        "roles": [
          {
            "company": {}
          }
        ]
      },
      "registrationStatus": {
        "personRoleStatus": {
          "reason": ["abc123"],
          "status": "abc123",
          "auctionAccessId": "123456789",
          "auctionId": "9876543210",
          "auctionName": "abc123"
        },
        "companyStatus": null
      },
      "statusCode": "BAD_REQUEST",
      "errorDetails": [
          {
            "errorCode": "NOT_FOUND",
            "field": "auctionId",
            "message": [
                "No Entity Could be Located."
            ]
          }
      ]
    }
  }
}

Additional Calls

• companyValidate - This operation is used to designate if a company has a valid membership in AuctionACCESS.
• companyRegister - This operation is used to register a company as doing business with a specific auction.

If you choose to make use of additional calls, please refer to the schemas for required fields and available response fields.

Common Errors & Issues

Invalid Person ID

{
  "data": {
    "validatePerson": {
      "person": null,
      "isValid": false,
      "issues": null,
      "statusCode": "BAD_REQUEST",
      "errorDetails": [
          {
            "errorCode": "BAD_REQUEST",
            "field": "auctionAccessId",
            "message": [
                "Invalid Person ID."
            ]
          }
      ]
    }
  }
}

Invalid Auction ID

{
  "data": {
    "validatePerson": {
      "person": null,
      "isValid": false,
      "issues": null,
      "message": "Invalid Auction Id",
      "statusCode": "BAD_REQUEST",
      "errorDetails": [
          {
            "errorCode": "BAD_REQUEST",
            "field": "auctionId",
            "message": [
                "Invalid Auction ID."
            ]
          }
      ]
    }
  }
}

No Entity Could Be Located

{
  "data": {
    "validatePerson": {
      "person": null,
      "isValid": false,
      "issues": null,
      "statusCode": "BAD_REQUEST",
      "errorDetails": [
          {
            "errorCode": "NOT_FOUND",
            "field": "auctionId",
            "message": [
                "No Entity Could be Located."
            ]
          }
      ]
    }
  }
}

Common reasons for this error include

• Invalid values for required parameters like last4PhotoId, auctionAccessId, lastName, etc.
• Excluded values for last4PhotoId, auctionAccessId, lastName, etc.

Membership Fee Due

{
  "data": {
    "validatePerson": {
      "person": null,
      "isValid": false,
      "issues": null,
      "message": "Membership Fee Due",
      "statusCode": "BAD_REQUEST",
      "errorDetails": [
          {
            "errorCode": "UNAUTHORIZED",
            "field": "auctionAccessId",
            "message": [
                "Membership Fee Due."
            ]
          }
      ]
    }
  }
}

Stage

https://webservices.stage-aa.auctionaccess.com/graphql

Production

https://webservices.prod-aa.auctionaccess.com/graphql