Procedure · POST

fyi.opensocial.provisionGroup

Create a group for a person and get the app a session on it.

Host-level: an app creates a group for a person and gets its own OAuth session on it. Authenticated twice: the person asking, by service auth from their PDS (they become the founder), and the app, by OAuth client authentication in the body (a client assertion for a confidential client) with a DPoP proof in the `DPoP` header, exactly as at the token endpoint. The app must be one this host provisions for. Returns the group and a token response bound to the proof's key, issued to the app's client id: refreshed, listed and revoked like any other session on the group.

Requires: an app the host provisions for

Input

handlestring · handlerequired

displayNamestringrequired

≤ 64 graphemes

descriptionstring

≤ 300 graphemes

joinPolicystring

metaReadableByarray of string

stewardsarray of string · did

Accounts that run the group alongside the founder.

scopestringrequired

The OAuth scope the app wants on the group. Must include `atproto`, and every entry must be one the app's client metadata declares.

client_idstringrequired

client_assertion_typestring

client_assertionstring

Output

didstring · didrequired

metastring · space-refrequired

membersstring · space-refrequired

sessionunknownrequired

An OAuth token response (access_token, token_type, refresh_token, expires_in, scope, sub), as /oauth/token returns it.

Errors

UntrustedApp
InvalidScope
use_dpop_nonce
HandleTaken

Schema

Lexicon JSON

{
  "lexicon": 1,
  "id": "fyi.opensocial.provisionGroup",
  "defs": {
    "main": {
      "type": "procedure",
      "description": "Host-level: an app creates a group for a person and gets its own OAuth session on it. Authenticated twice: the person asking, by service auth from their PDS (they become the founder), and the app, by OAuth client authentication in the body (a client assertion for a confidential client) with a DPoP proof in the `DPoP` header, exactly as at the token endpoint. The app must be one this host provisions for. Returns the group and a token response bound to the proof's key, issued to the app's client id: refreshed, listed and revoked like any other session on the group.",
      "input": {
        "encoding": "application/json",
        "schema": {
          "type": "object",
          "required": [
            "handle",
            "displayName",
            "scope",
            "client_id"
          ],
          "properties": {
            "handle": {
              "type": "string",
              "format": "handle"
            },
            "displayName": {
              "type": "string",
              "maxGraphemes": 64,
              "maxLength": 640
            },
            "description": {
              "type": "string",
              "maxGraphemes": 300,
              "maxLength": 3000
            },
            "joinPolicy": {
              "type": "string"
            },
            "metaReadableBy": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "stewards": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "did"
              },
              "description": "Accounts that run the group alongside the founder."
            },
            "scope": {
              "type": "string",
              "description": "The OAuth scope the app wants on the group. Must include `atproto`, and every entry must be one the app's client metadata declares."
            },
            "client_id": {
              "type": "string"
            },
            "client_assertion_type": {
              "type": "string"
            },
            "client_assertion": {
              "type": "string"
            }
          }
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "type": "object",
          "required": [
            "did",
            "meta",
            "members",
            "session"
          ],
          "properties": {
            "did": {
              "type": "string",
              "format": "did"
            },
            "meta": {
              "type": "string",
              "format": "space-ref"
            },
            "members": {
              "type": "string",
              "format": "space-ref"
            },
            "session": {
              "type": "unknown",
              "description": "An OAuth token response (access_token, token_type, refresh_token, expires_in, scope, sub), as /oauth/token returns it."
            }
          }
        }
      },
      "errors": [
        {
          "name": "UntrustedApp"
        },
        {
          "name": "InvalidScope"
        },
        {
          "name": "use_dpop_nonce"
        },
        {
          "name": "HandleTaken"
        }
      ]
    }
  }
}

← All host extensions