fetchToken
FetchToken gets a user token that is the basis for making secure API calls on behalf of a Bonanza user. With a verified user token, you can do things like add items to a user's booth, or get information on items from that booth that are not yet available for sale.
After getting a user token with this call, you must send the user a URL, which they will use to verify that your business has permission to interact with Bonanza on their behalf. User tokens must be verified by the user before they can be used.
For more information about how user tokens work, see our intro to user tokens.
Take a look at some examples in C#, Java, PHP, Python, and Ruby.
fetchToken Input
fetchToken is a secure API method with the following URL and HTTP header requirements:
| Submit to URL: | https://api.bonanza.com/api_requests/secure_request |
| Required in HTTP header: | X-BONANZLE-API-DEV-NAME set to your dev_id |
| X-BONANZLE-API-CERT-NAME set to your cert_id |
Note that all secure methods except for fetchToken and getBoothItems require you to submit a user token so that we know what user account you are acting on behalf of. For details about setting up and submitting user tokens, see our intro to user tokens.
The name for your request should be fetchTokenRequest.
Here are the available input parameters that can be serialized into JSON:
| Argument | Type | Occurrence | Meaning |
|---|---|---|---|
| validationCompleteURL | uri | optional | After user successfully validates your token, we will provide them a button to proceed to this URL, if provided. |
| registrationData | container | Optional | Registration data, for a user that is signing up anew. |
| registrationData.firstName | string | Optional | First name of user |
| registrationData.lastName | string | Optional | Last name of user |
| registrationData.city | string | Optional | City of user |
| registrationData.state | string | Optional | State or province of user |
| registrationData.country | string | Optional | Two digit country code |
| registrationData.zipCode | string | Optional | ZIP/Postal code of user |
| registrationData.email | string | Optional | Email address of user |
fetchToken Output
The name for the output returned from this request is fetchTokenResponse. So, after parsing the serialized response into JSON, you can access the data with something like my_json_hash['fetchTokenResponse']
Here are all the possible output parameters:
| Argument | Type | Occurrence | Meaning |
|---|---|---|---|
| Standard Output Fields | |||
| errorMessage | Container | Conditionally | Description of an error or warning that occurred when Bonanza processed the request. Not returned if the ack value is Success. |
| errorMessage.error | Container |
Conditionally, repeatable: [0..*] |
|
| errorMessage.error.category | ErrorCategory | Conditionally | Currently unused. |
| errorMessage.error.message | string | Conditionally | A description of the error |
| errorMessage.error.type | ErrorType | Conditionally | A unique descriptive name for the error. |
| warnings | Container | Conditionally | Description of a warning that occurred when Bonanza processed the request. |
| warnings.unrecognized_parameters | Container |
Conditionally, repeatable: [0..*] |
An array of unrecognized parameters. |
| Call-specific Output Fields | |||
| authToken | string | Always | The token you will submit to Bonanza to indicate that you want to interact with this user. |
| authenticationURL | anyURI | Always | The URL to which you should send the user to verify that they want to authorize you to act on their behalf. The user will be presented with a login screen that tells them they are authorizing your business to take authorized actions. After they login, the auth token will be verified and you can start making secure calls using the user token. You will be sent an email at the address you associated with your Bonapitit account when user tokens are verified. |
| emailRecognized | boolean | Conditionally, if email was passed | True if the email addressed passed with registrationData already exists as an active user, false if it doesn't. If the email field wasn't passed in registrationData, this won't be returned. |
| hardExpirationTime | datetime | Always | The date that this token expires. By default, it will expire one year after you acquire it. The user can also elect to expire the token early through their Bonanza account. |
