---
title: Binary resources
description: Examples in this documentation depend on features activated in the ds-evaluation setup profile.
component: pingds
version: 8.1
page_id: pingds:rest-guide:binary-rest
canonical_url: https://docs.pingidentity.com/pingds/8.1/rest-guide/binary-rest.html
revdate: 2025-10-22T14:42:39Z
keywords: ["REST API"]
section_ids:
  binary-rest-update: Add a binary resource
  binary-rest-read: Read a binary resource
---

# Binary resources

|   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Examples in this documentation depend on features activated in [the `ds-evaluation` setup profile](../install-guide/setup-ds.html#about-ds-evaluation).The code samples demonstrate how to contact the server over HTTPS using the deployment CA certificate. Before trying the samples, generate the CA certificate in PEM format from the server deployment ID and password:```console
$ dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile ca-cert.pem
``` |

## Add a binary resource

1. Get the base64-encoded string representation of the binary resource to upload.

   For example, save the JPEG photo, [picture.jpg](../_attachments/images/picture.jpg), to the current directory and convert it to a base64-encoded string:

   ```console
   $ base64 encode --rawDataFile picture.jpg
   ```

   > **Collapse: Show output**
   >
   > ```
   > /9j/4AAQSkZJRgABAQEAYABgAAD/4QAWRXhpZgAASUkqAAgAAAAAAAAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AAf/Z
   > ```

2. Upload the string representation of the binary resource.

   The following example updates Babs Jensen's resource to add or replace the profile photo:

   * Curl

   * JavaScript

   * Python

   * Ruby

   ```console
   $ curl \
    --request PUT \
    --cacert ca-cert.pem \
    --user dc=com/dc=example/ou=People/uid=kvaughan:bribery \
    --header 'Content-Type: application/json' \
    --data '{"photo": "/9j/4AAQSkZJRgABAQEAYABgAAD/4QAWRXhpZgAASUkqAAgAAAAAAAAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AAf/Z"}' \
    'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen'
   ```

   ```javascript
   (async () => {
       const { authenticate, doRequest, getOptions } = require('./utils')
       const photo = { "photo": "/9j/4AAQSkZJRgABAQEAYABgAAD/4QAWRXhpZgAASUkqAAgAAAAAAAAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AAf/Z" }
       const resource = '/hdap/dc=com/dc=example/ou=People/uid=bjensen'
       const options = getOptions({ method: 'PUT', path: resource, body: photo })
       const jwt = await authenticate(options)
       options.headers['Authorization'] = 'Bearer ' + jwt
       const response = await doRequest('HDAP: add photo', options)
       console.log(response)
   })().catch(error => { console.error(error) })
   ```

   Source files for this sample: [binary-add.js](../_attachments/hdap/js/binary-add.js), [utils.js](../_attachments/hdap/js/utils.js)

   ```python
   #!/usr/bin/env python3

   import requests
   import utils

   photo = { 'photo': '/9j/4AAQSkZJRgABAQEAYABgAAD/4QAWRXhpZgAASUkqAAgAAAAAAAAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AAf/Z' }
   jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
   headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
   response = requests.put(
       f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=bjensen',
       headers=headers,
       json=photo,
       verify=utils.ca_pem)
   print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))
   ```

   Source files for this sample: [utils.py](../_attachments/hdap/py/utils.py), [binary-add.py](../_attachments/hdap/py/binary-add.py)

   ```ruby
   require_relative 'utils.rb'
   require 'faraday'
   require 'json'

   utils = Utils.new('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
   options = { ca_file: utils.ca_pem }
   jwt = utils.authenticate
   hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", ssl: options) do |f|
       f.headers['Content-Type'] = 'application/json'
       f.request :authorization, 'Bearer', jwt
   end
   photo = { "photo" => "/9j/4AAQSkZJRgABAQEAYABgAAD/4QAWRXhpZgAASUkqAAgAAAAAAAAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AAf/Z" }
   response = hdap.put do |h|
       h.path = 'dc=com/dc=example/ou=People/uid=bjensen'
       h.body = JSON.generate(photo)
   end

   puts "Status code: #{response.status}\nJSON: #{response.body}"
   ```

   Source files for this sample: [utils.rb](../_attachments/hdap/rb/utils.rb), [binary-add.rb](../_attachments/hdap/rb/binary-add.rb)

   HDAP Ruby examples require Ruby 3.2 and the `faraday` and `json` gems.

## Read a binary resource

1. Read the binary resource as a base64-encoded JSON string.

   The following example reads Babs Jensen's profile photo:

   * Curl

   * JavaScript

   * Python

   * Ruby

   ```console
   $ curl \
    --cacert ca-cert.pem \
    --user dc=com/dc=example/ou=People/uid=kvaughan:bribery \
    'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=photo&_prettyPrint=true'
   ```

   > **Collapse: Show output**
   >
   > ```
   > {
   >   "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
   >   "_rev" : "<revision>",
   >   "photo" : [ "/9j/4AAQSkZJRgABAQEAYABgAAD/4QAWRXhpZgAASUkqAAgAAAAAAAAAAAD/2wBDAAEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/2wBDAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQH/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AAf/Z" ]
   > }
   > ```

   ```javascript
   (async () => {
       const { authenticate, doRequest, getOptions } = require('./utils')
       const resource = '/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=photo'
       const options = getOptions({ path: resource })
       const jwt = await authenticate(options)
       options.headers['Authorization'] = 'Bearer ' + jwt
       const response = await doRequest('HDAP: read photo', options)
       console.log(response)
   })().catch(error => { console.error(error) })
   ```

   Source files for this sample: [binary-read.js](../_attachments/hdap/js/binary-read.js), [utils.js](../_attachments/hdap/js/utils.js)

   ```python
   #!/usr/bin/env python3

   import requests
   import utils

   params = { '_fields': 'photo' }
   jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
   headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
   response = requests.get(
       f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=bjensen',
       headers=headers,
       params=params,
       verify=utils.ca_pem)
   print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))
   ```

   Source files for this sample: [utils.py](../_attachments/hdap/py/utils.py), [binary-read.py](../_attachments/hdap/py/binary-read.py)

   ```ruby
   require_relative 'utils.rb'
   require 'faraday'

   utils = Utils.new('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
   options = { ca_file: utils.ca_pem }
   jwt = utils.authenticate
   fields = { "_fields": "photo" }
   hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: fields, ssl: options) do |f|
       f.headers['Content-Type'] = 'application/json'
       f.request :authorization, 'Bearer', jwt
   end
   response = hdap.get('dc=com/dc=example/ou=People/uid=bjensen')

   puts "Status code: #{response.status}\nJSON: #{response.body}"
   ```

   Source files for this sample: [utils.rb](../_attachments/hdap/rb/utils.rb), [binary-read.rb](../_attachments/hdap/rb/binary-read.rb)

   HDAP Ruby examples require Ruby 3.2 and the `faraday` and `json` gems.