• Get Started
  • Documentation
  • Samples
  • Blog
  • Pricing
    • Start Free
    Table of contents
    Overview
    Tutorials
    Samples
    Changelog
    Scenes
    This API is a Technical Preview and is available for testing purposes only. Do not use in production.
    Create scene share
    post https://dev-api.bentley.com/scenes/{sceneId}/shares?iTwinId

    Creates a new scene share.

    Creating a Scene Share allows your scene to be publicly accessible, enabling anyone with the shareKey to view its data without needing to sign in. To use a share, take the value of the shareKey property and prepend it with the Basic prefix in the authorization header of your request.

    If no expiration is provided, it will default to 100 years from creation (effectively non-expiring).

    Shares may be revoked at any time via the Revoke scene share endpoint. Deleting a scene automatically revokes its shares.

    Request

    Request parameters

    Name
    Required?
    Description
    sceneId
    Yes

    Scene Id

    iTwinId
    Yes

    Primary iTwin Id associated with the scene

    Request headers

    Name
    Required?
    Description
    Authorization
    Yes

    OAuth access token with itwin-platform scope

    Accept
    Yes

    Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

    Request body

    SceneShareCreateDTO

    Name
    Type
    Required?
    Description
    expiration
    Date-time
    No

    Optional share expiration timestamp (must be a future date)

    Example

    json
    {
    "expiration": "2027-05-07T08:00:00-04:00"
}

    Response

    Response 201 Created

    Created share.

    json
    {
    "share": {
        "id": "e047c23b-6fe1-4629-abda-1344f98236d7",
        "sceneId": "eda9e67f-24a3-4bd5-aeca-981d2abdb610",
        "iTwinId": "1ba4c28a-e518-42d4-85e4-ff9f9ef44bb6",
        "contractName": "SceneDefault",
        "shareKey": "eyJhbGciOiJ...",
        "expiration": "2027-05-07T08:00:00-04:00",
        "createdById": "37f457a6-25fd-4d4a-8947-974b690158be",
        "lastModifiedById": "37f457a6-25fd-4d4a-8947-974b690158be",
        "creationTime": "2025-05-04T00:14:08-04:00",
        "lastModified": "2025-05-06T21:15:25-04:00"
    }
}

    Response 400 Bad Request

    Unprocessable Entity

    json
    {
    "error": {
        "code": "InvalidScenesRequest",
        "message": "Cannot create sceneShare.",
        "target": "sceneShare",
        "details": [{
            "code": "InvalidRequestBody",
            "message": "Expiration must be a valid date in the future.",
            "target": "expiration"
        }]
    }
}

    Response 401 Unauthorized

    This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

    json
    {
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

    Response 403 Forbidden

    Forbidden

    json
    {
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

    Response 404 Not Found

    Not Found

    json
    {
    "error": {
        "code": "SceneNotFound",
        "message": "Requested scene is not available.",
        "target": "scene"
    }
}

    Response 409 Conflict

    Conflict

    json
    {
    "error": {
        "code": "SceneShareConflict",
        "message": "Private scenes cannot be publicly shared. Change visibility to 'iTwin' first."
    }
}

    Response 429 Too many requests

    This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

    json
    {
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

    Response headers

    Name
    Description
    retry-after

    Number of seconds to wait until client is allowed to make more requests.

    Definitions

    Error

    Contains error information.

    Name
    Type
    Description
    code
    String

    One of a server-defined set of error codes.

    target
    String, null

    The target of the error.

    message
    String

    A human-readable representation of the error.

    Error Response

    Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

    Name
    Type
    Description
    error
    Error

    Error information.

    SceneShareDTO

    Name
    Type
    Description
    id
    Uuid

    Globally unique identifier for the share

    iTwinId
    Uuid

    iTwin id

    sceneId
    Uuid

    Id of the scene being shared

    shareKey
    String

    The share key to be used for authentication to the share.

    expiration
    Date-time

    The expiration for the share as an ISO8601 string, 'YYYY-MM-DDTHH:mm:ss.sssZ'

    createdById
    Uuid

    Id of the user who created the scene share

    contractName
    String

    Share contract name

    creationTime
    Date-time

    Time the scene share was created as an ISO8601 string, 'YYYY-MM-DDTHH:mm:ss.sssZ'

    lastModified
    Date-time

    Time the scene share was last modified as an ISO8601 string, 'YYYY-MM-DDTHH:mm:ss.sssZ'

    lastModifiedById
    Uuid

    Id of the user who last modified the scene share

    SceneShareResponse

    Name
    Type
    Description
    share
    SceneShareDTO

    SceneShareCreateDTO

    Name
    Type
    Description
    expiration
    Date-time

    Optional share expiration timestamp (must be a future date)

    Was this page helpful?