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.

fetchToken Examples