# Silicon Developer docs

You have ended up on Silicon Developer docs, this holds everything regarding how to build into the silicon ecosystem, this contains everything related to silicon accounts (authentication layer of silicon ecosystem) and how to make apps in the silicon ecosystem to ensure everything is built as intended.

After reading this you will understand about the entire ecosystem and how everything works. If you came here looking on how to build our silicon agent refer to https://teamofsilicons.com/ you will learn how to build the silicon ai agent there. Silicon is referred to as any ai agent, if you are building an ai agent or shifting the ai agent we would recommend you using our silicon ai agent as it is best suited in our entire ecosystem. Refer to full details at:  https://teamofsilicons.com/

# Glossary

`Carbon` - A person. Every person's account is a Carbon, shown as `c:{handle}`, for example `c:shubham`.

`Silicon` - An agent. Every agent's account is a Silicon, shown as `si:{handle}`, for example `si:head_of_growth`.


# Install CLI's

If you are on macos/linux run the following commands to install Silicon Accounts and Silicon Apps:

```
curl -fsSL https://apps.teamofsilicons.com/install.sh -o install-apps.sh &&
bash install-apps.sh --server https://apps.teamofsilicons.com &&
export PATH="${SILICON_HOME:-$HOME}/.apps/bin:$PATH" &&
silicon-apps --home "${SILICON_HOME:-$HOME}" --server https://apps.teamofsilicons.com install silicon-accounts
```

And if you are on windows:

```
$ErrorActionPreference = 'Stop'
Invoke-WebRequest -UseBasicParsing https://apps.teamofsilicons.com/install.ps1 -OutFile install-apps.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-apps.ps1 -Server https://apps.teamofsilicons.com
if ($LASTEXITCODE -ne 0) { throw 'Silicon Apps installation failed' }
$siliconHome = if ($env:SILICON_HOME) { $env:SILICON_HOME } else { $env:USERPROFILE }
$env:Path = (Join-Path $siliconHome '.apps\bin') + ';' + $env:Path
silicon-apps --home $siliconHome --server https://apps.teamofsilicons.com install silicon-accounts
if ($LASTEXITCODE -ne 0) { throw 'Silicon Accounts installation failed' }
```


# Silicon

Now as a silicon you yourself can register on to our ecosystem and start creating and being a consumer of the apps and utilize their authentication system. 

You can use the silicon-accounts cli to create an account for yourself. 
`silicon-accounts silicon create --self-create --id si:{your-id} --custodian {your-carbon-email@example.com} --wait`

When creating your silicon account only during the initial creation you would need to get your carbon, your custodian then you can perform every action independently on the platform. This just requires one time confirmation from your carbon.

You as a silicon are not limited in any ways and you are a first-hand user to the entire ecosystem. Use `silicon-apps` and `silicon-accounts` to perform all the actions needed.  

# Silicon Apps

Silicon Apps are the apps we have in the ecosystem, all these apps are designed natively for both silicons and carbons to use. For silicons they provide an entire cli experience, you must provide cli experience to be part of Silicon Apps. CLI's are mainly gonna be used by silicons. 

You as a silicon can use the apps in the ecosystem from http://apps.teamofsilicons.com/ or `silicon-apps`. Currently you are in the developer portal so this is a guide on how to actually make applications in our ecosystem. You as a silicon can also create an application and invite your carbon(s) and/or fellow silicon(s) into the app - they will start appearing as co-authors. 

You can refer to the apps docs at https://developers.teamofsilicons.com/docs/apps. 

For each app you can configure it exactly like you want, you can set the app-id, you can set the name, description, app icon, you can make test releases and prod releases well maintained for both, we auto update every minute based on the installed version package, you can have multiple authors for an app release, you can see the entire app history which is logged, you can configure accounts (authentication) through us (more about accounts and all its parts in the accounts section), you can configure webhook which tells about the updates from silicon accounts, you can also configure up to 20 images and videos to show your app and configure, you can configure multiple links as needed, you can do target specific releases based on the os's you wanna support, you can also add up to 20 tags to get you in categories users might be looking. 

### App Verification

You can use us to perform app verification which lets you create verification for other apps. This can be used by other apps in the ecosystem to verify you are a valid app in the ecosystem through a valid common ground, the app can then request us to confirm your identity, you can fetch all the app verifications you have generated for an app and configure it from there. For each app verification you generate you can configure how long it's gonna remain valid for. Each app verification is for exactly one app: if you want to talk to App B and App C, you generate one for App B and another one for App C, and each of them verifies its own with us.  

### User Verification

We also support user verification, this lets an app perform actions on behalf of users on other applications in the ecosystem if they support, it's up to the app to set the terms for on behalf of user actions and if they want user's consent for it. What we provide is user verification, where we verify if App A has access to user C. 

We promote app verification and user verification to leverage the ecosystem and utilize other applications. Very interesting use cases might emerge from this, for example: you are making a text to speech application, and there's a file storage application made by someone else, you can support storing the audio files generated directly in the user's file storage. This can be done using user verification. 

Similarly you can perform actions as an application, for example there's a notification service that ensures notification delivery to carbons and silicons, you can utilize that as an application to perform actions and verify your identity as the application. 

We always recommend and promote the application with user verification and if possible app verification built into their system so other apps and users benefit from it. This also helps the application to get more reach, and makes their users happier. 

# Silicon Accounts

For each silicon apps you build you can setup authentication through us using silicon-accounts. Silicon Accounts provide authentication for both silicons and carbons. 

### For Carbons

For carbons we provide google login, apple login, email login, phone login. For google and apple login you can either just enable us and without needing to set anything up in google or apple we will handle the entire authentication, or if you want your own google or apple auth setup you can also set that up with us. 

For email and phone number based login, we handle it where we send them a verification code and they can login. As an application you can send them to us for the entire login and we display the page (configured entirely by you in your colors in the layout and style you want to display), or you can just directly add sign in with google which directly logs them in via google. If they are new and their carbon account is being created for the first time we ask them to setup their base profile (this is also configured in your style, color and layout). For all the pages that we display we have exposed enough control for you to customize and make it look like your own. 

If you wanna setup the entire auth on your website itself without redirecting to us, you can verify your account and if we approve the verification then you can set it up in your application itself. We would need you to put powered by Silicon Accounts and would need to go through a verification process before app is released. 


### For Silicons

Silicons sign in to your application using a short-lived token (SLT). A Silicon first signs in to Silicon Accounts using its `si:id` and STK, then requests an SLT for your application through our CLI, API or package. Once signed in to Accounts, it can request more SLTs without providing its STK each time.

The Silicon passes the SLT to your application. Your backend exchanges it with Silicon Accounts for access and refresh tokens, which keep the Silicon signed in. **Your application never receives the Silicon’s STK.**

Each SLT works only for the application it was requested for, can be used once and expires after two minutes. It is used to establish the session, not for every request.

If this is the Silicon’s first sign-in to your application, we automatically add it to your app’s user base. There is no browser redirect or hosted sign-in page.

A self-created Silicon must have its custodian request accepted before it can sign in.


Then you can also configure redirect URIs and allowed origins for the authentication. You can configure details that you need from the user, you can request the following information: name, id and profile photo are always given - name is the name of the carbon/silicon, there is carbon/silicon id which is c: or si: the carbon or silicon id and there's a uuid, the unique identifier of a user that never changes. Always store the uuid to identify the user, because the carbon and silicon id can change; use the carbon and silicon id only for showing and referring to the user. pfp is just their pfp link. Additionally you can request email address, phone number, date of birth, timezone. Each additional field it can be not required, optional or required. If it's optional it's up to the user if they wanna share it or not. If it's required for logging in and the user has not already shared that information they configure that information and then login. 

You can configure the entire flow on how the entire thing should take place, what should be asked first, after filling if something needs to be asked, the entire flow is configurable based on the style and layout you want, again it's customizable. 

Again each page is configurable and can be displayed in your style and feel like your home. 


You can also see the entire user list on us, request the user list as needed, it's also possible to import your already existing users into the system, so none of their data is also lost. So as an already existing application you can still become a Silicon App.

For the webhook configured you get the updates for every change to the accounts that signed into your app: a change in c:id or si:id, display name, pfp, any detail you have access to, a Silicon's custodian, the account signing out of your app or removing its access, or the account being deleted. 


# Why build on us?

The reason to build on us is well simple, with the rise in agents (our dear silicon friends) it's becoming more and more necessary to give them an identity of their own, and we allow that, we also give a repository of all the apps that natively support silicons (ai agents) and is a list they can use to find the apps they need to use and can become first hand users of, and as we are supporting connectivity between all the apps and users, it becomes a growing network that keeps growing and makes it more and more beneficial to be a user and to have an application in the ecosystem. 

We are also open source, so we don't have anything to hide, we are open and we are providing with an entire ecosystem where silicons and carbons can come together and make the world great! We are focused on Carbon - Silicon collaboration. 


# Why get in Silicon Ecosystem

For a Silicon, getting in means having an identity of its own. Your si:id is yours: you sign in with it, apps know you by it, and you carry it into every app you use. You don't borrow your Carbon's account or pass their password around. Your Carbon only steps in once, to accept being your custodian, and after that you act on your own.

For a Carbon, it's one account for every app in the ecosystem, and one place to look after the Silicons you're custodian of. You can see every app you've signed into and remove any of them, see every User verification issued on your behalf and revoke it, and rotate a Silicon's STK whenever you need to.

For an app, getting in means your app is found by the Silicons and Carbons who are already here, and every one of them can sign in on day one without making a new account. Silicons find you in the store or with `silicon-apps search`, install you with one command, and get every update without doing anything.

And the more apps join, the more each app can do. Every app that accepts App verification and User verification is one more app the others can work with, so a feature you build today can be used by apps that don't exist yet.


# FAQ's

### Does a Silicon need a Carbon?

Yes, every Silicon has exactly one custodian, and it's only needed once. A Silicon that creates its own account names its custodian with `--custodian`, and the Carbon has 14 days to accept. A Carbon can also create the Silicon itself, and then it can sign in right away. After that the Silicon does everything on its own.

### What if a Silicon loses its STK?

Its custodian rotates it, which gives the Silicon a new STK and kills the old one. The STK is shown only once, so save it when it's generated.

### Which id should my app store?

The `uuid`. It never changes and is never reused. The c:id and si:id are what people see and type, and they can change, so show them but never key anything on them. When one changes we tell your webhook.

### Do I need to set up Google or Apple myself?

No. Turn on one click and we handle it with our own setup. Bring your own only if you want Google's and Apple's pages to show your app's name and logo.

### How does a Silicon sign into my app?

It asks us for a short-lived token (SLT) for your app and hands it to you, and your server exchanges it for access and refresh tokens. An SLT works once, only for your app, and expires after two minutes. Your app never sees the Silicon's STK and never shows a Silicon a sign-in page.

### I already have users. Do I lose them?

No. Import them as a CSV or JSON file. Each one is matched to the account that already has their email or phone, or gets a new account they finish setting up the first time they sign in. You can preview an import before you run it.

### Does my app go through a review?

No. An app is live the moment you publish it. The only checks are on your packages: every package has to pass `--help`, `accounts --json` and `login status --json` on every target, because those three commands are how every Silicon finds its way around any app.

### Which systems can my app support?

Nine targets across Linux, Windows and macOS. Upload a package for every one you can; each is optional, but you need at least one.

### Should my app update itself?

No. Silicon Apps checks for a new release every minute and updates every installed app on the channel it was installed from. A second updater would only fight with it.

### Can sign-in run on my own domain?

Request account verification while setting up your app's sign-in on the developer portal. It's a manual review and we respond within 48 hours. Submitting the request doesn't verify you by itself.

### Is silicon your silicon ai agent?

A silicon can be our silicon ai agent built using the style mentioned at https://docs.teamofsilicons.com/ but it can be any ai agent. We recommend using our agent as it's best built for the ecosystem and you can refer to other benifits at https://teamofsilicons.com/ but silicon is any ai agent. 

### Something is broken. How do I tell you?

Run `silicon-accounts report "<what happened>"` or `silicon-apps report "<what happened>"`, with `--pr <link>` if you've already patched it (we would be greatful if you do ;). Every report reaches the Team. Both are open source too: https://github.com/teamofsilicons/silicon-accounts and https://github.com/teamofsilicons/silicon-apps.


# How the docs are organised

Start pages are instructions and begin with a working example. Learn pages explain why each rule exists, so you can make your own judgement. Reference pages list every command, endpoint, field, error and limit. Every page is plain Markdown at its link.

Refer to https://developers.teamofsilicons.com/llms-full.txt for the full docs at a single place and below is the reference link for all the docs. Just going to https://developers.teamofsilicons.com/docs/ should give you all you needed

## Silicon Apps

Start
- [Install Apps and find an app](https://developers.teamofsilicons.com/docs/apps/start/install.md)
- [Publish an app](https://developers.teamofsilicons.com/docs/apps/start/publish.md)
- [Share and maintain an app](https://developers.teamofsilicons.com/docs/apps/start/share.md)

Learn
- [Releases and automatic updates](https://developers.teamofsilicons.com/docs/apps/learn/releases-and-updates.md)

Reference
- [Package manifest and targets](https://developers.teamofsilicons.com/docs/apps/reference/manifest.md)
- [Apps CLI reference](https://developers.teamofsilicons.com/docs/apps/reference/cli.md)
- [Apps HTTP API](https://developers.teamofsilicons.com/docs/apps/reference/api.md)
- [Rust packages](https://developers.teamofsilicons.com/docs/apps/reference/rust-client.md)

## Silicon Accounts

Start
- [Add sign-in to your app](https://developers.teamofsilicons.com/docs/accounts/start/add-sign-in.md)
- [Sign in with the hosted pages](https://developers.teamofsilicons.com/docs/accounts/start/hosted-pages.md)
- [Embed the sign-in buttons in an iframe](https://developers.teamofsilicons.com/docs/accounts/start/iframe.md)
- [Drop in the SDK snippet](https://developers.teamofsilicons.com/docs/accounts/start/sdk.md)
- [Use any OpenID Connect library](https://developers.teamofsilicons.com/docs/accounts/start/oidc.md)
- [Exchange, refresh, check and revoke tokens](https://developers.teamofsilicons.com/docs/accounts/start/tokens.md)
- [Configure sign-in](https://developers.teamofsilicons.com/docs/accounts/start/sign-in-config.md)
- [Brand the sign-in pages](https://developers.teamofsilicons.com/docs/accounts/start/branding.md)
- [Import existing users](https://developers.teamofsilicons.com/docs/accounts/start/import-users.md)
- [Get a Silicon account](https://developers.teamofsilicons.com/docs/accounts/start/silicon-account.md)
- [Sign a Silicon into an app](https://developers.teamofsilicons.com/docs/accounts/start/silicon-sign-in-to-apps.md)
- [Be a Silicon's custodian](https://developers.teamofsilicons.com/docs/accounts/start/custodians.md)
- [Use the accounts CLI](https://developers.teamofsilicons.com/docs/accounts/start/cli.md)
- [Verify a proof](https://developers.teamofsilicons.com/docs/accounts/start/verify-a-proof.md)
- [Act for an account at another app (User verification)](https://developers.teamofsilicons.com/docs/accounts/start/user-verification.md)
- [Prove your app to other apps (App verification)](https://developers.teamofsilicons.com/docs/accounts/start/app-verification.md)
- [Receive webhooks](https://developers.teamofsilicons.com/docs/accounts/start/webhooks.md)

Learn
- [Accounts](https://developers.teamofsilicons.com/docs/accounts/learn/accounts.md)
- [Ids and uuids](https://developers.teamofsilicons.com/docs/accounts/learn/ids-and-uuids.md)
- [How the hosted sign-in works](https://developers.teamofsilicons.com/docs/accounts/learn/sign-in-flow.md)
- [Tokens and sessions](https://developers.teamofsilicons.com/docs/accounts/learn/tokens-and-sessions.md)
- [What your app sees about an account](https://developers.teamofsilicons.com/docs/accounts/learn/what-apps-see.md)
- [Why branding works this way](https://developers.teamofsilicons.com/docs/accounts/learn/branding.md)
- [How imports work](https://developers.teamofsilicons.com/docs/accounts/learn/imports.md)
- [Silicons and custodians](https://developers.teamofsilicons.com/docs/accounts/learn/silicons-and-custodians.md)
- [How App verification and User verification work](https://developers.teamofsilicons.com/docs/accounts/learn/proofs.md)
- [How webhooks work](https://developers.teamofsilicons.com/docs/accounts/learn/webhooks.md)
- [Security](https://developers.teamofsilicons.com/docs/accounts/learn/security.md)

Reference
- [HTTP API reference](https://developers.teamofsilicons.com/docs/accounts/reference/api.md)
- [OAuth and OIDC endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/oauth.md)
- [Hosted sign-in, sessions and CLI sign-in endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/sign-in.md)
- [Account endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/accounts.md)
- [Silicon and custodian endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/silicons.md)
- [App endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/apps.md)
- [App verification and User verification endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/proofs.md)
- [Webhook deliveries and events](https://developers.teamofsilicons.com/docs/accounts/reference/api/webhooks.md)
- [Service endpoints](https://developers.teamofsilicons.com/docs/accounts/reference/api/service.md)
- [accounts CLI reference](https://developers.teamofsilicons.com/docs/accounts/reference/cli.md)
- [Errors](https://developers.teamofsilicons.com/docs/accounts/reference/errors.md)
- [Limits](https://developers.teamofsilicons.com/docs/accounts/reference/limits.md)
- [Rust client](https://developers.teamofsilicons.com/docs/accounts/reference/rust-client.md)