Live State

What Vellby has provisioned into this app. Resets on pod restart.

SCIM Endpoints

SCIM 2.0 (RFC 7642–7644) is a standard HTTP API for automating user/group provisioning. Vellby acts as the provider; your app is the consumer.

Users

Groups

Connect Guide

1. Create an app entity in Vellby
2. Set attributes: {"service":"mock","scim_token":"any-secret","scim_endpoint":"https://mock-app.vellby.com/scim/v2"}
3. Connect that app entity to one or more context entities
4. Vellby will push group/user changes to this URL automatically on every connection change

Key implementation rules

Test with curl

Create a user

curl -X POST https://mock-app.vellby.com/scim/v2/Users   -H "Authorization: Bearer any-token"   -H "Content-Type: application/json"   -d '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
       "userName":"alice@example.com","displayName":"Alice"}'

Add member to group

curl -X PATCH https://mock-app.vellby.com/scim/v2/Groups/entity-42   -H "Authorization: Bearer any-token"   -H "Content-Type: application/json"   -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
       "Operations":[{"op":"add","path":"members",
         "value":[{"value":"user-uuid","display":"Alice"}]}]}'

Remove member

curl -X PATCH https://mock-app.vellby.com/scim/v2/Groups/entity-42   -H "Authorization: Bearer any-token"   -H "Content-Type: application/json"   -d '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
       "Operations":[{"op":"remove","path":"members[value eq \"user-uuid\"]"}]}'

AP Live State

ActivityPub actors created on this mock service and their follower counts from Vellby.

ActivityPub Endpoints

ActivityPub (W3C Recommendation) is a decentralised social protocol. Each Vellby entity becomes an Actor. Any ActivityPub-compatible service (Mastodon, Ghost, Lemmy, Pixelfed) can follow it without SCIM or Keycloak.

Vellby-side endpoints (on api.vellby.com)

ActivityPub Connect Guide

To federate your service with Vellby entities:

1. Expose GET /.well-known/webfinger — return a JRD with a self link to your Actor URL
2. Expose GET /ap/actors/{id} — return an Actor document with inbox, followers, and publicKey
3. Expose POST /ap/actors/{id}/inbox — accept and verify signed activities
4. On receiving a Follow from Vellby: add the follower and send an Accept back to their inbox
5. Deliver content as Create activities to all followers' inboxes, signed with your Actor's private key

HTTP Signature verification (pseudocode)

sig_header = request.headers["Signature"]
params = parse_key_value(sig_header)  # keyId, headers, signature
actor = GET(params["keyId"].split("#")[0])  # fetch remote Actor
pem   = actor["publicKey"]["publicKeyPem"]
signed_string = rebuild_signed_string(params["headers"], request)
verify_rsa_sha256(pem, signed_string, base64.decode(params["signature"]))

ActivityPub Test with curl

Discover an actor via WebFinger

curl "https://mock-app.vellby.com/.well-known/webfinger?resource=acct:design-team@mock-app.vellby.com"   -H "Accept: application/jrd+json"

Fetch Actor document

curl https://mock-app.vellby.com/ap/actors/design-team   -H "Accept: application/activity+json"

Send a Follow activity (no sig check in mock)

curl -X POST https://mock-app.vellby.com/ap/actors/design-team/inbox   -H "Content-Type: application/activity+json"   -d '{
    "@context": "https://www.w3.org/ns/activitystreams",
    "type": "Follow",
    "actor": "https://api.vellby.com/ap/entities/5",
    "object": "https://mock-app.vellby.com/ap/actors/design-team"
  }'

Discover a Vellby entity as an AP Actor

curl "https://api.vellby.com/.well-known/webfinger?resource=acct:entity-5@api.vellby.com"   -H "Accept: application/jrd+json"

VC Live State

Recent Verifiable Credentials submitted to the verifier on this demo service.

DID + VC Endpoints

W3C Decentralized Identifiers (DIDs) give each entity a portable, self-sovereign identity. Verifiable Credentials (VCs) let Vellby issue cryptographically signed membership proofs that any service can verify offline — no runtime dependency on Vellby.

This mock service (demo)

Vellby-side endpoints (on api.vellby.com)

VC Connect Guide

To accept Vellby-issued VCs as proof of entity membership:

1. User calls GET https://api.vellby.com/api/credentials/entity/{id}?user_id={uuid} — receives a JWT VC
2. User presents the JWT to your service (Authorization header, POST body, QR code, etc.)
3. Your service decodes the JWT header to get alg: RS256
4. Extract iss from JWT payload — this is the issuer DID, e.g. did:web:api.vellby.com
5. Resolve the DID: fetch https://api.vellby.com/.well-known/did.json
6. Extract verificationMethod[0].publicKeyJwk — convert to RSA public key
7. Verify the JWT RS256 signature
8. Check exp (not expired), credentialSubject.entity_id matches your expected entity
9. Grant access based on credentialSubject.role

VC payload structure

{
  "iss": "did:web:api.vellby.com",
  "sub": "did:web:api.vellby.com:users:{keycloak-uuid}",
  "iat": 1234567890,
  "exp": 1266103890,
  "vc": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": ["VerifiableCredential", "EntityMembership"],
    "issuer": "did:web:api.vellby.com",
    "credentialSubject": {
      "id": "did:web:api.vellby.com:users:{uuid}",
      "entity_id": 5,
      "entity_name": "Design Team",
      "entity_type": "context",
      "role": "member"
    }
  }
}

VC Verifier

Paste a JWT issued by GET https://api.vellby.com/api/credentials/entity/{id}?user_id={uuid} to inspect it.